Last updated: June 27, 2009

Ivan Marsic
Department of Electrical and Computer Engineering

Preface

This book reviews important technologies for software development with a particular focus on Web applications. In reviewing these technologies I put emphasis on underlying principles and basic concepts, rather than meticulousness and completeness. In design and documentation, if conflict arises, clarity should be preferred to precision because, as will be described, the key problem of software development is having a functioning communication between the involved human parties. Solving a problem by an effective abstraction and representation is a recurring theme of software engineering. The particular technologies evolve or become obsolete, but the underlying principles and concepts will likely resurface in new technologies. This text provides background understanding, making it easier to follow complete and detailed expositions of current technologies that can be found elsewhere.

Audience
This book is designed for upper-division undergraduate and graduate courses in software engineering. It intended primarily for learning, rather than reference. I also believe that the books focus on core concepts should be appealing to practitioners who are interested in the whys behind the software engineering tools and techniques that are commonly encountered. I assume that the readers will have some familiarity with programming languages and I do not cover any programming language in particular. Basic knowledge of discrete mathematics and statistics is desirable for some advanced topics, particularly in Chapters 3 and 4. Most concepts do not require mathematical sophistication beyond a first undergraduate course.

Approach and Organization

The first part (Chapters 15) is intended to accompany a semester-long hands-on team project in software engineering. In the spirit of agile methods, the project consists of two iterations, both focused around the same software product. The first iteration is exploratory and represents the first attempt at developing the proposed software product. This usually means developing some key functions and sizing the effort to set more realistic goals in the second iteration. In the second iteration the students should perform the necessary adjustments, based on what they have learned in the first iteration. The second part (Chapters 68 and most Appendices) is intended for a semester-long course on software engineering of Web applications. It also assumes a hands-on student team project. The focus is on the server-side of Web applications and communication between clients and servers. I omitted the user interface design issues because I feel that proper treatment of this topic requires a book on its own. I tried to make every chapter self-contained, so that entire chapters can be skipped if necessary. The text follows this outline.

Ivan Marsic

Rutgers University

ii

Chapter 2 introduces object-oriented software engineering. It is short enough to be covered in few weeks, yet it provides sufficient knowledge for students to start working on the first iteration of their software product. In general, this knowledge may be sufficient for amateur software development, on relatively small and non-mission-critical projects. Chapters 3 through 5 offer more detailed coverage of the topics introduced in Chapter 2. They are intended to provide the foundation for subsequent iterations of a software product. Chapters 6 8 provide advanced topics which can be covered selectively, if time permits, or in a follow-up course dedicated to software engineering of web applications. This is not a programming text, but several appendices are provided as reference material for special topics that will inevitably arise in some software projects.

Examples, Code, and Solved Problems

I tried to make this book as practical as possible by using realistic examples and working through their solutions. I usually find it difficult to bridge the gap between an abstract design and coding. Hence, I include a great deal of code. The code is in the Java programming language, which brings me to another point. Different authors favor different languages and students often complain about having to learn yet another language. I feel that the issue of selecting a programming language for a software engineering textbook is artificial. Programming language is a tool and the software engineer should master a toolbox of languages so to be able to choose the tool that best suits the task at hand. Every chapter (except for Chapters 1 and 9) is accompanied with a set of problems. Solutions for most of the problems can be found at the back of the text, starting on page 366. Additional information about team projects and online links to related topics can be found at the book website: http://www.ece.rutgers.edu/~marsic/books/SE/ .

Contents at a Glance

CHAPTER 1 CHAPTER 2 CHAPTER 3 CHAPTER 4 CHAPTER 5 CHAPTER 6 CHAPTER 7 CHAPTER 8 CHAPTER 9 APPENDIX A APPENDIX B APPENDIX C APPENDIX D APPENDIX E APPENDIX F

INTRODUCTION .......................................................................................................... 1 OBJECT-ORIENTED SOFTWARE ENGINEERING .............................................................. 47 MODELING AND SYSTEM SPECIFICATION ................................................................... 115 SOFTWARE MEASUREMENT AND ESTIMATION ............................................................. 161 DESIGN WITH PATTERNS ......................................................................................... 186 XML AND DATA REPRESENTATION ........................................................................... 238 SOFTWARE COMPONENTS ....................................................................................... 280 WEB SERVICES ..................................................................................................... 293 FUTURE TRENDS.................................................................................................... 329 JAVA PROGRAMMING ............................................................................................. 336 NETWORK PROGRAMMING ...................................................................................... 337 HTTP OVERVIEW ................................................................................................... 351 DATABASE-DRIVEN WEB APPLICATIONS ................................................................... 360 DOCUMENT OBJECT MODEL (DOM) ......................................................................... 361 USER INTERFACE PROGRAMMING ............................................................................. 364

SOLUTIONS TO SELECTED PROBLEMS ................................................................................................. 366 REFERENCES ........................................................................................................................... 401

ACRONYMS AND ABBREVIATIONS ....................................................................................................... 411 INDEX ........................................................................................................................... 413

iii

Ivan Marsic

Rutgers University

iv

Table of Contents

PREFACE

................................................................................................................................ I

CONTENTS AT A GLANCE ..................................................................................................................... III TABLE OF CONTENTS .......................................................................................................................... IV CHAPTER 1 1.1

1.1.1 1.1.2

INTRODUCTION .......................................................................................................... 1 What is Software Engineering? ...................................................................................... 1

Why Software Engineering Is Difficult...................................................................................... 6 Book Organization ................................................................................................................ 7

1.2
1.2.1 1.2.2 1.2.3 1.2.4 1.2.5

Software Engineering Lifecycle ...................................................................................... 7

Symbol Language ............................................................................................................... 10 Requirements Analysis and System Specification .................................................................. 11 Object-Oriented Analysis and the Domain Model.................................................................... 13 Object-Oriented Design ....................................................................................................... 14 Project Estimation and Product Quality Measurement............................................................. 16

1.3
1.3.1 1.3.2

Case Studies.............................................................................................................. 19
Case Study 1: From Home Access Control to Adaptive Homes................................................ 21 Case Study 2: Personal Investment Assistant ........................................................................ 24

1.4
1.4.1 1.4.2 1.4.3

Object Model .............................................................................................................. 33

Relationships and Communication........................................................................................ 34 Example............................................................................................................................. 36 Design of Objects................................................................................................................ 37

1.5
1.5.1 1.5.2 1.5.3

Student Team Projects ................................................................................................ 38

Stock Market Investment Fantasy League ............................................................................. 38 Web-based Stock Forecasters ............................................................................................. 40 Remarks about the Projects ................................................................................................. 43

1.6 CHAPTER 2 2.1

2.1.1

Summary and Bibliographical Notes ............................................................................. 44 OBJECT-ORIENTED SOFTWARE ENGINEERING .............................................................. 47 Software Development Methods................................................................................... 48
Agile Development .............................................................................................................. 49

Software Engineering

Contents

2.2
2.2.1 2.2.2 2.2.3

Requirements Engineering .......................................................................................... 51

Types of Requirements........................................................................................................ 54 User Stories for Agile Development ...................................................................................... 55 Requirements Gathering Strategies ...................................................................................... 58

2.3
2.3.1 2.3.2 2.3.3 2.3.4 2.3.5

Use Case Modeling..................................................................................................... 59

Actors, Goals, and Sketchy Use Cases ................................................................................. 59 System Boundary and Subsystems....................................................................................... 64 Detailed Use Case Specification........................................................................................... 66 Risk Analysis and Reduction ................................................................................................ 74 Why Software Engineering Is Difficult (1)............................................................................... 74

2.4
2.4.1 2.4.2 2.4.3

Analysis: Building the Domain Model ............................................................................ 75

Identifying Concepts............................................................................................................ 76 Concept Associations and Attributes ..................................................................................... 80 Contracts: Preconditions and Postconditions ......................................................................... 82

2.5
2.5.1 2.5.2 2.5.3

Design: Assigning Responsibilities ............................................................................... 83

Design Principles for Assigning Responsibilities..................................................................... 87 Class Diagram.................................................................................................................... 92 Why Software Engineering Is Difficult (2)............................................................................... 94

2.6 2.7
2.7.1

Software Architecture .................................................................................................. 94 Implementation and Testing......................................................................................... 95

Software Testing............................................................................................................... 100

2.8

Summary and Bibliographical Notes ........................................................................... 103

Problems............................................................................................................................ 107 CHAPTER 3 3.1

3.1.1 3.1.2 3.1.3 3.1.4 3.1.5

MODELING AND SYSTEM SPECIFICATION ................................................................... 115 What is a System? .................................................................................................... 116
World Phenomena and Their Abstractions........................................................................... 117 States and State Variables................................................................................................. 120 Events, Signals, and Messages.......................................................................................... 126 Context Diagrams and Domains ......................................................................................... 127 Systems and System Descriptions...................................................................................... 130

3.2
3.2.1 3.2.2 3.2.3 3.2.4

Notations for System Specification ............................................................................. 130

Basic Formalisms for Specifications.................................................................................... 131 UML State Machine Diagrams............................................................................................ 138 UML Object Constraint Language (OCL) ............................................................................. 141 TLA+ Notation .................................................................................................................. 146

3.3
3.3.1 3.3.2

Problem Frames ....................................................................................................... 148

Problem Frame Notation.................................................................................................... 148 Problem Decomposition into Frames................................................................................... 150

Ivan Marsic

Rutgers University

vi

3.3.3 3.3.4

Composition of Problem Frames......................................................................................... 152 Models............................................................................................................................. 153

3.4 3.5

Specifying Goals....................................................................................................... 154 Summary and Bibliographical Notes ........................................................................... 155

Problems............................................................................................................................ 156 CHAPTER 4 4.1

4.1.1

SOFTWARE MEASUREMENT AND ESTIMATION ............................................................. 161 Fundamentals of Measurement Theory....................................................................... 162
Measurement Theory ........................................................................................................ 163

4.2
4.2.1 4.2.2

What to Measure? .................................................................................................... 164

Cyclomatic Complexity ...................................................................................................... 165 Use Case Points ............................................................................................................... 167

4.3
4.3.1 4.3.2

Measuring Module Cohesion...................................................................................... 176

Internal Cohesion or Syntactic Cohesion ............................................................................. 176 Semantic Cohesion ........................................................................................................... 178

4.4
4.4.1

Psychological Complexity .......................................................................................... 179

Algorithmic Information Content.......................................................................................... 179

4.5
4.5.1

Effort Estimation ....................................................................................................... 181

Deriving Project Duration from Use Case Points................................................................... 182

4.6

Summary and Bibliographical Notes ........................................................................... 183

Problems............................................................................................................................ 185 CHAPTER 5 5.1

5.1.1 5.1.2 5.1.3

DESIGN WITH PATTERNS ......................................................................................... 186 Indirect Communication: Publisher-Subscriber............................................................. 187

Applications of Publisher-Subscriber ................................................................................... 194 Control Flow ..................................................................................................................... 195 Pub-Sub Pattern Initialization ............................................................................................. 197

5.2
5.2.1 5.2.2

More Patterns........................................................................................................... 197

Command ........................................................................................................................ 198 Proxy............................................................................................................................... 199

5.3
5.3.1 5.3.2 5.3.3 5.3.4

Concurrent Programming .......................................................................................... 201

Threads ........................................................................................................................... 202 Exclusive Resource AccessExclusion Synchronization ...................................................... 204 Cooperation between ThreadsCondition Synchronization .................................................. 206 Concurrent Programming Example ..................................................................................... 207

5.4
5.4.1 5.4.2

Broker and Distributed Computing .............................................................................. 213

Broker Pattern .................................................................................................................. 216 Java Remote Method Invocation (RMI)................................................................................ 218

5.5

Information Security .................................................................................................. 225

Software Engineering

Contents

vii

5.5.1 5.5.2 5.5.3

Symmetric and Public-Key Cryptosystems........................................................................... 227 Cryptographic Algorithms................................................................................................... 228 Authentication................................................................................................................... 230

5.6

Summary and Bibliographical Notes ........................................................................... 231

Problems............................................................................................................................ 233 CHAPTER 6 6.1

6.1.1 6.1.2 6.1.3 6.1.4

XML AND DATA REPRESENTATION ........................................................................... 238 Structure of XML Documents ..................................................................................... 241
Syntax ............................................................................................................................. 241 Document Type Definition (DTD) ........................................................................................ 247 Namespaces .................................................................................................................... 251 XML Parsers .................................................................................................................... 253

6.2
6.2.1 6.2.2 6.2.3 6.2.4 6.2.5

XML Schemas .......................................................................................................... 255

XML Schema Basics ......................................................................................................... 256 Models for Structured Content............................................................................................ 261 Datatypes......................................................................................................................... 264 Reuse.............................................................................................................................. 271 RELAX NG Schema Language........................................................................................... 271

6.3
6.3.1 6.3.2

Indexing and Linking ................................................................................................. 272

XPointer and Xpath ........................................................................................................... 272 XLink ............................................................................................................................... 273

6.4 6.5

Document Transformation and XSL ............................................................................ 274 Summary and Bibliographical Notes ........................................................................... 277

Problems............................................................................................................................ 278 CHAPTER 7 7.1 7.2

7.2.1 7.2.2 7.2.3

SOFTWARE COMPONENTS ....................................................................................... 280 Components, Ports, and Events ................................................................................. 281 JavaBeans: Interaction with Components.................................................................... 282
Property Access................................................................................................................ 283 Event Firing...................................................................................................................... 283 Custom Methods............................................................................................................... 284

7.3
7.3.1 7.3.2 7.3.3

Computational Reflection........................................................................................... 285

Run-Time Type Identification.............................................................................................. 286 Reification ........................................................................................................................ 287 Automatic Component Binding ........................................................................................... 288

7.4 7.5
7.5.1 7.5.2

State Persistence for Transport .................................................................................. 288 A Component Framework .......................................................................................... 289
Port Interconnections ........................................................................................................ 289 Levels of Abstraction ......................................................................................................... 291

Ivan Marsic

Rutgers University

viii

7.6

Summary and Bibliographical Notes ........................................................................... 292

Problems............................................................................................................................ 292 CHAPTER 8 8.1 8.2

8.2.1 8.2.2 8.2.3 8.2.4

WEB SERVICES ..................................................................................................... 293 Service Oriented Architecture .................................................................................... 295 SOAP Communication Protocol.................................................................................. 296
The SOAP Message Format .............................................................................................. 297 The SOAP Section 5 Encoding Rules ................................................................................. 302 SOAP Communication Styles ............................................................................................. 305 Binding SOAP to a Transport Protocol ................................................................................ 308

8.3
8.3.1 8.3.2 8.3.3 8.3.4 8.3.5

WSDL for Web Service Description ............................................................................ 309

The WSDL 2.0 Building Blocks ........................................................................................... 310 Defining a Web Services Abstract Interface ........................................................................ 313 Binding a Web Service Implementation ............................................................................... 315 Using WSDL to Generate SOAP Binding............................................................................. 316 Non-functional Descriptions and Beyond WSDL................................................................... 317

8.4 8.5
8.5.1 8.5.2

UDDI for Service Discovery and Integration................................................................. 318 Developing Web Services with Axis ............................................................................ 319
Server-side Development with Axis..................................................................................... 319 Client-side Development with Axis ...................................................................................... 325

8.6 8.7

OMG Reusable Asset Specification ............................................................................ 326 Summary and Bibliographical Notes ........................................................................... 327

Problems............................................................................................................................ 328 CHAPTER 9 9.1 9.2 9.3 9.4 9.5 9.6 9.7 APPENDIX A A.1 APPENDIX B B.1 B.2 FUTURE TRENDS.................................................................................................... 329 Aspect-Oriented Programming ................................................................................... 330 OMG MDA ............................................................................................................... 331 Autonomic Computing ............................................................................................... 331 Software-as-a-Service (SaaS).................................................................................... 332 End User Software Development................................................................................ 332 The Business of Software .......................................................................................... 335 Summary and Bibliographical Notes ........................................................................... 335 JAVA PROGRAMMING ............................................................................................. 336 Introduction to Java Programming .............................................................................. 336 NETWORK PROGRAMMING ...................................................................................... 337 Socket APIs ............................................................................................................. 337 Example Java Client/Server Application ...................................................................... 342

Software Engineering

Contents

ix

B.3 B.4 APPENDIX C C.1 C.2 C.3 APPENDIX D APPENDIX E E.1 APPENDIX F F.1 F.2

Example Client/Server Application in C ....................................................................... 345 Windows Socket Programming .................................................................................. 347 HTTP OVERVIEW ................................................................................................... 351 HTTP Messages....................................................................................................... 352 HTTP Message Headers ........................................................................................... 356 HTTPSSecure HTTP ............................................................................................. 359 DATABASE-DRIVEN WEB APPLICATIONS ................................................................... 360 DOCUMENT OBJECT MODEL (DOM) ......................................................................... 361 Core DOM Interfaces ................................................................................................ 361 USER INTERFACE PROGRAMMING ............................................................................. 364 Model/View/Controller Design Pattern......................................................................... 364 UI Design Recommendations..................................................................................... 364

SOLUTIONS TO SELECTED PROBLEMS ................................................................................................. 366 REFERENCES ........................................................................................................................... 401

ACRONYMS AND ABBREVIATIONS ....................................................................................................... 411 INDEX ........................................................................................................................... 413

Chapter 1
Introduction

Contents
There is nothing new under the sun but there are lots of old things we dont know. Ambrose Bierce, The Devils Dictionary

1.1 What is Software Engineering?

1.1.1 1.1.2 Why Software Engineering Is Difficult 1.1.3 Book Organization

As with any engineering activity, a software engineer starts with problem definition and applies tools of the trade to obtain a problem solution. However, unlike any other engineering, software engineering seems to put great emphasis on methodology or method for obtaining a solution, rather than on tools and techniques. Experts justify this with the peculiar nature of the problems solved by software engineering. These wicked problems can be properly defined only after being solved.

1.2 Software Engineering Lifecycle

1.2.1 Symbol Language 1.2.2 Requirements Analysis and System Specification 1.2.3 Object-Oriented Analysis and the Domain Model 1.2.4 Object-Oriented Design 1.2.5

1.3 Case Studies

1.3.1 Case Study 1: From Home Access Control to Adaptive Homes 1.3.2 Case Study 2: Personal Investment

1.4 Object Model

1.4.1 Relationships and Communication 1.4.2 Example 1.4.3 Design of Objects 1.4.4 1.4.5

1.1 What is Software Engineering?

To the optimist, the glass is half full. To the pessimist, the glass is half empty. To the engineer, the glass is twice as big as it needs to be. Anonymous

1.5 Student Team Projects

1.5.1 Stock Market Investment Fantasy League 1.5.2 Web-based Stock Forecasters 1.5.3 Remarks about the Projects

1.6 Summary and Bibliographical Notes

Computer science is no more about computers than astronomy is about telescopes. Edsger W. Dijkstra

Most of software engineering books leave you with the impression that software engineering is all about project management. In other words, it is not about the engineering per se but it is more about how you go about engineering software, in particular, knowing what are the appropriate steps to take and how you put them together. Management is surely important, particularly because most software projects are done by teams, but the engineering aspect of it ends up being neglected. Here I focus more on the engineering aspects of software engineering. I try to show that there are interesting intellectual puzzles and exciting solutions, and that software engineering is not only admonition after admonition, or a logistics and management cookbook.

Ivan Marsic

Rutgers University

Setting posts

Cutting wood

Nailing

Painting

Figure 1-1: Illustration of complexity on the problem of scheduling construction tasks.

A computational system (further on called system) is a computer-based system whose purpose is to answer questions about and/or support human actions in some domain. We say that the system is about its domain. It incorporates internal structures representing the domain. These structures include data representing entities and relations in the domain, and a program prescribing how these data may be manipulated. Computation actually results when a processor (interpreter or CPU) is executing this program or a part of it. I hope to convey in this text that software is many parts, each of which is individually easy, but the problem is that there are too may of them. It is not the difficulty of individual components; it is the multitude that overwhelms youyou simply lose track of bits and pieces. Let me illustrate this point on a simple example. Suppose one wants to construct a fence around a house. The construction involves four tasks: setting posts, cutting wood, painting, and nailing (Figure 1-1). Setting posts must precede painting and nailing, and cutting must precede nailing. Suppose that setting posts takes 3 units of time, cutting wood takes 2 units of time, painting takes 5 units of time for uncut wood and 4 units of time otherwise, and nailing takes 2 units of time for unpainted wood and 3 units of time otherwise. In what order should these tasks be carried out to complete the project in the shortest possible time? It is difficult to come up with a correct solution (or, solutions) without writing down possible options and considering them one by one (unless one comes with a built-in computer chip). It is hard to say why this problem is complicated, because no individual step seems to be difficult. After all, the most complicated operation involves adding small integer numbers. Software engineering is full of problems like this: all individual steps are easy, yet the overall problem is overwhelming. The problem is, for discrete logic, closeness to being correct is not acceptable; one flipped bit can change the entire sense of a program1. Software developers have not yet found adequate methods
1

Software engineers like to think that their problems are unique for all of engineering or even for broader humanity problems. But the classical nursery rhyme reminds me that perils of overlooking the details were known at least as far back as the battle of Bosworth Field and the times of Richard III (1452-1485): For want of a nail the shoe was lost. For want of a shoe the horse was lost. For want of a horse the rider was lost.

Chapter 1

Introduction

Programmer Programmer Customer Customer

Figure 1-2: The role for software engineering. to handle such complexity, and this text is mostly dedicated to present the current state of the knowledge of handling the complexity of software development. Software engineering is often confused with programming. The role of software engineering is to capture the customers business needs and specify the blueprints for the system so that programmers can implement it (Figure 1-2). Software engineering relies on our ability to think about space and time, processes, and interactions between processes and structures. Consider an example of designing a software system to operate an automatic bank machine, known as Automatic Teller Machine (ATM) (Figure 1-3). Most of us do not know what is actually going on inside an ATM box; nonetheless, we could offer a naive explanation of how ATM machines work. We know what that an ATM machine allows us to deposit or withdraw money, and we can imagine how to split these activities into simpler activities to be performed by imaginary little agents working inside the machine (see illustration in Figure 1-4). We will call the entities inside the system concepts because they are imaginary. As seen, there are two types of concepts: workers and things.

For want of a rider the battle was lost. For want of a battle the kingdom was lost. And all for want of a horseshoe nail.

Ivan Marsic

Rutgers University

1
8
5

6 9

Communication link

ATM machine Bank customer

Banks remote datacenter

Figure 1-3: Example: developing software for an Automatic Teller Machine (ATM). We know that an ATM machine plays the role of a bank window clerk (teller). The reader may wonder why we should imagine many virtual agents doing a single tellers job. Why not simply imagine a single virtual agent doing the tellers job?! The reason is that this would not help much is because all we would accomplish is to transform one complicated and inscrutable object (an ATM machine) into another complicated and inscrutable object (a virtual teller). To understand a complex thing, one needs to develop ideas about relationships among the parts inside. By dividing a complicated job into simpler tasks and describing how they interact, we simplify the problem and make it easier to understand and solve. This is why imagination is critical for software engineering (as it is for any other problem-solving activity!). Of course, it is not enough to uncover the static structure of the planned system, as is done in Figure 1-4. We also need to describe how the system elements (workers and things) interact during the task accomplishment. Figure 1-5 illustrates step-by-step interactions. In a way, software development parallels the problem-solving strategies in artificial intelligence (AI): represent the goal; represent the current state; and, minimize the differences by means-ends analysis. As any with design, software design can be seen as a difference-reduction activity, formulated in terms of a symbolic description of differences. Finally, in autonomic computing, the goals are represented explicitly in the program that implements the system.

Chapter 1

Introduction

Domain Model

How may I help you?

Transaction record Cash

Speakerphone

Bookkeeper Safe keeper Safe Phone

Window clerk Datacenter liaison

Dispenser

Customer

Banks remote datacenter

Figure 1-4: Imagined static structure of ATM shows internal components and their roles.

Enter your PIN

B
Verify this account

Verify account XYZ

Typing in PIN number

XYZ valid. Balance: $100

Account valid. Balance: $100

How may I help you?

Release $60

Record $60 less

Withdraw $60

Dispense $60

H
Please take your cash

Dispensing!

Figure 1-5: Dynamic interactions of the imagined components during task accomplishment.

Ivan Marsic

Rutgers University

Programming language, like any other formal language, is a set of symbols and rules for manipulating them. It is when they need to meet the real world that you discover that associations can be made in different ways and some rules were not specified. A novice all too often sees only benefits of building a software product and ignores and risks. An expert sees a broader picture and anticipates the risks. After all, dividing the problem in sub-problems and conquering them piecewise does not guarantee logical rigor and strict consistency between the pieces. Risks typically include such as, the program can do what is expected of it and then some more, unexpected capabilities. Another risk is that not all environment states are catalogued before commencing the program development. Depending on how you frame assumptions, you can come up with a solution. The troubles arise if the assumptions happen to be inaccurate, wrong, or get altered due to the changing world. We always have: USER COMP.SYS ENVIRONMENT When developing a system, we are modeling the user and environment in the computer system. Modeling necessarily involves simplification and abstraction. The purpose of simplification is to make the development manageable. The system solves one problem, not all problems.

1.1.1

Why Software Engineering Is Difficult

Software is like entropy. It is difficult to grasp, weighs nothing, and obeys the second law of thermodynamics; i.e., it always increases. Norman R. Augustine

If you are a civil engineer building bridges then all you need to know is about bridges. Unlike this, if you are developing software you need to know about software domain (because that is what you are building) and you need to know about the problem domain (because that is what you are building a solution for). Some problems require extensive periods of dedicated research (years, decades, or even longer). Obviously, we cannot consider such problem research as part of software engineering. We will assume that the problem is either solved (a solution exists), or it can be solved in a relatively short amount of time by an informed non-expert. A further problem is that software is a formal domain, while the real world is informal. Solving problems in these different domains demands different styles and there is a need to eventually reconcile these styles. A narrow interpretation of software engineering deals only with engineering the software itself. This means, given a precise statement of what needs to be programmed, narrow-scope software engineering is concerned with the design, implementation, and testing of a program that represents a solution to the stated problem. A broader interpretation of software engineering includes discovering a solution for a real-world problem. The real-world problem may have nothing to do with software. For example, the real-world problem may be a medical problem of patient monitoring, or a financial problem of devising trading strategies. In broad-scope software engineering there is no precise statement of what needs to be programmed. Our task amounts to none less than engineering of change in a current business practice. One could go even further and argue that the second law of thermodynamics works against software engineers (or anyone else trying to build models of the world), as well. Software engineering is mainly about modeling the physical world and finding good abstractions. If you find a representative set of abstractions, the development flows naturally. However, finding abstractions in a problem domain (also known as application domain) involves certain level of

Chapter 1

Introduction

coarse graining. This means that our abstractions are unavoidably just approximationswe cannot describe the problem domain in perfect detail: after all that would require working at the level of atomic or even subatomic particles. Given that every physical system has very many parts, the best we can do is to describe it in terms of only some of its variables. Working with approximations is not necessarily a problem by itself should the world structure be never changing. But, the second law of thermodynamics states that the universe tends towards increasing disorder. We live in a changing world: things wear out and break, organizations go bankrupt or get acquired or restructured, business practices change, and so on. Whatever order was captured in those comparatively few variables that we started with, tends to get dispersed, as time goes on, into other variables where it is no longer counted as order. Our (approximate) abstractions necessarily become invalid with passing time and we need to start afresh. This requires time and resources which we may not have available. Software development still largely depends on heroic effort of select few developers. Product line and development standardization are still largely missing, but there are efforts in this direction. Tools and metrics for product development and project management are the key and will be given considerable attention in this text.

1.1.2

Book Organization

Chapter 2 offers a quick tour of software engineering. The main focus is on tools, not methodology, for solving software engineering problems. Chapter 3 elaborates on techniques for problem specification. Chapter 4 describes metrics for measuring the software process and product quality. Chapter 5 elaborates on techniques for problem solution, but unlike Chapter 2 it focuses on advanced tools for software design. Chapter 6 describes structured data representation using XML. Chapter 7 presents software components. Chapter 8 introduces service-oriented architectures and Web services. I adopt an incremental and iterative refinement approach to presenting the material. For every new topic, we will scratch the surface and move on, only to revisit later and dig deeper.

1.2 Software Engineering Lifecycle

The Feynman Problem-Solving Algorithm: (i) Write down the problem (ii) think very hard, and (iii) write down the answer.

Any product development can be expected to proceed as an organized process that usually includes the following phases: Planning / Specification Design Implementation Evaluation

Ivan Marsic

Rutgers University

So is with software development. The common software development phases are as follows: 1. Specification / Requirements Documenting the usage scenarios and deriving the static domain model

2. Design Assigning responsibilities to objects and specifying the dynamics of their interactions under different usage scenarios

3. Implementation Encoding the design in a programming language

4. Testing Individual classes/components (unit testing) and entire system (integration testing)

5. Operation and Maintenance Running the system; Fixing bugs and adding new features

The lifecycle usually comprises many other activities, some of which precede the above ones, such as marketing survey to determine the market need for the planned product. This text is restricted to engineering activities, usually undertaken by the software developer. The early inspiration for software lifecycle came from other engineering disciplines, where the above activities usually proceed in a sequential manner (or at least it was thought so). This method is known as waterfall process because developers build monolithic systems in one fell swoop. It requires completing the artifacts of the current phase before proceeding to the subsequent one. However, over the years the developers noticed that software development is unlike any other product development in the following aspects: Unlike most of other products, software is intangible and hard to visualize. Most people experience software through what it does: what inputs it takes and what it generates as outputs Software is probably the most complex artifacta large software product consists of so many bits and pieces as well as their relationships, every single one having an important roleone flipped bit can change the entire sense of a program Software is probably the most flexible artifactit can be easily and radically modified at any stage of the development process (or, at least it is so perceived)

These insights led to adopting incremental and iterative (or, evolutionary) development methods. These methods are also recently characterized as agile. A popular incremental and iterative process is called Unified Process [Jacobson et al., 1999]. Each iteration should involve progressing through the design in more depth. Incremental and iterative process seeks to get to a working instance2 as soon as possible. Having a working instance available lets the interested parties to have something tangible, to play with and make inquiries. Through this experimentation
2

This is not necessarily a prototype, because prototype creates impression of something that will be thrown away after initial experimentation. Conversely, a working instance can evolve into the actual product.

Chapter 1

Introduction

(preferably by end users), unsuspected deficiencies are discovered that drive a new round of development using failures and the knowledge of things that would not work as a springboard to new approaches. This greatly facilitates the consensus reaching and building the understanding of all parties of what needs to be developed and what to expect upon the completion. So, the key of incremental and iterative methods is to progressively deepen the understanding or visualization of the target product, by both advancing and retracting to earlier activities to rediscover more of its features. All lifecycle processes have a goal of incremental refinement of the product design, but different people hold different beliefs on how is this to be achieved. This has been true in the past and it continues to be true, and I will occasionally comment on different approaches. Personally, I enthusiastically subscribe to the incremental and iterative approach, and in that spirit the exposition in this text progresses in an incremental and iterative manner, by successively elaborating the software lifecycle phases. For every new topic, we will scratch the surface and move on, only to revisit later and dig deeper. A quick review of any software engineering textbook reveals that software engineering is largely about management. Project management requires organizational and managerial skills such as identifying and organizing the many tasks comprising a project, allocating resources to complete those tasks, and tracking actual against expected/anticipated resource utilization. Successful software projects convey a blend of careful objective evaluation, adequate preparation, continuous observation and assessment of the environment and progress, and adjusting tactics. It is interesting to compare the issues considered by Brooks [1975] and compare those of the recent agile methods movementboth put emphasis on communication of the development team members. My important goal here is, therefore, to present the tools that facilitate communication among the developers. The key such tools are: Modular design: Breaking up the system in modules helps to cope with complexity; however, the modularization can be done in many ways with varying quality of the results. Symbolic language: The Unified Modeling Language (UML) is used similar to how the symbols such as , , , and , are used in mathematics. They abbreviate the exposition of the material and facilitate the readers understanding of the material. Project and product metrics: Metrics for planning and measuring project progress, and metrics for measuring the quality of software products are essential for engineering approach to software development. Design heuristics: Also known as patterns, they convey the best practices that were proven in many contexts and projects.

Partitioning a problem into simpler ones, so called divide-and-conquer approach, is common when dealing with complex problems. In software development it is embodied in modularity: The source code for a module can be written and maintained independently of the source code for other modules. As with any activity, the value of a structured approach to software development becomes apparent only when complex tasks are tackled.

Ivan Marsic

Rutgers University

10

1.2.1

Symbol Language
There are only 10 types of people in this world. Those who know binary, and those who dont. Unknown

As part of a design process, it is essential to communicate your ideas. When describing a process of accomplishing a certain goal, person actually thinks in terms of the abbreviations and symbols as they describe the details of what she is doing, and could not proceed intelligently if she were not to do so. George Miller found in the 1950s that human short-term memory can store about seven items at a time [Miller, 1957]. The short-term memory is what we use, for instance, to remember a telephone number just long enough to look away from the paper on which it is written to dial the number. It is also known as working memory because in it information is assumed to be processed when first perceived. It has been likened to the RAM (random access memory) of a computer. Recall how many times you had to look back in the middle of dialing, particularly if you are not familiar with the area code, which makes the number a difficult 10 digits! It turns out that the Millers hypothesis is valid for any seven items, which could be anything, such as numbers, faces, people, or communitiesas we organize information on higher levels of abstraction, we can still remember seven of whatever it is. This is called chunking. Symbols can be easier chunked into patterns, which are represented by new symbols. Using symbols and hierarchical abstraction makes it easier for people to think about complex systems. As can be observed throughout this text, the basic notation is often trivial and can be mastered relatively quickly. The key is in the skills in creating various modelsit can take considerable amount of time to gain this expertise. Our primary symbol language is UML, but it is not strictly adhered to throughout the text. I will use other notations or an ad-hoc designed one if I feel that it conveys the message in a more elegant way. Example UML symbols are shown in Figure 1-6. To become familiar with UML, you can start at http://www.uml.org, which is the official standards website. People usually use different symbols for different purposes and at different stages of progression. During development there are many ways to think about your design, and many ways to informally describe it. Any design model or modeling language has limits to what it can express and no one view of a design tells all. For example, strict adherence to a standard may be cumbersome for the initial sketches; contrariwise, documenting the completed design is always recommended in UML. UML is probably the most widely accepted graphical notation for software design. However, it is not generally accepted and it is often criticized (e.g., for not being consistent), but everybody would agree that symbols are useful, so different authors invent their own favorite symbols. Even in mathematics, the ultimate language of symbols, there are controversies about symbols even for such established subjects as calculus (cf., Newtons vs. Leibnitzs symbols for calculus), lest to bring up more recent subjects. To sum up, you can invent your own symbols if you feel it absolutely necessary, but before using them, explain their meaning/semantics and ensure that it is always easy to look-up the meanings of your symbols.

Chapter 1

Introduction

11

interface BaseInterface ClassName # attribute_1 : int # attribute_2 : boolean # attribute_3 : String + operation_1() : void + operation_2() : String + operation_3(arg1 : int) Class1Implement + operation() Class2Implement + operation() + operation()

Stereotype provides additional info/ annotation/ explanation

Three common compartments: 1. 2. 3. Classifier name Attributes Operations

Inheritance relationship: BaseInterface is implemented by two classes

Software Class Software Interface Implementation

Actor

Comment

instance1 : Class1

instance5 : Class2

instance8 : Class3

doSomething()

doSomethingElse()

Interaction Diagram
doSomethingYetElse()

Figure 1-6: Example UML symbols for software concepts.

1.2.2

Requirements Analysis and System Specification

We start with the customer statement of requirements, if the project is sponsored by a specific customer, or the vision statement, if the project does not have a sponsor. The vision statement is similar to the customer statement of requirements in that it briefly describes what the envisioned system is about, followed by a list of features/services it will provide or tasks/activities it will support. Given the customer statement of requirements, the first step in the software development process is called requirements analysis or systems analysis. During this activity the developer attempts to expand and amplify the statement of requirements and produce the system specificationthe document that is an exact description of what a planned system is to do. Requirements analysis delimits the system and specifies the services it offers, identifies the types of users that will interact with the system, and identifies other systems that interact with ours. The system is at first considered a black box, its services (push buttons) are identified, and typical interaction scenarios are detailed for each service. Requirement analysis includes both fact-finding about how is the problem solved in the current practice as well as envisioning how the planned system might work. Recall the ATM machine example from Figure 1-3. We identified the relevant players in Figure 1-4. However, this may be too great a leap for a complex system. A more gradual approach is to start with identifying the external players and their step-by-step interactions. Figure 1-7(a) shows the players external to the system (called actors). What happens inside the system is considered separately in the design and analysis phases (described in the following sections). One of the key techniques for requirements analysis is use case modeling. A set of use cases describes the elemental tasks a system is to perform and the relation between these tasks and the

Ivan Marsic

Rutgers University

12

(a)
Bank customer

1
7
4

2
9

System (ATM machine)

Banks remote datacenter

(b)

Window clerk

Datacenter liaison

Bookkeeper

Safe keeper

Dispenser

Speakerphone

Telephone

Transaction record

Safe

Cash

Figure 1-7: Gallery of actors (a) and concepts (b) of the system under discussion. The actors are relatively easy to identify because they are external to the system and visible; conversely, the concepts are hard to identify because they are internal to the system, hence invisible/imaginary. outside world. Each use case description represents a dialog between the user and the system, with the aim of helping the user achieve a business goal. In each dialog, the user initiates actions and the system responds with reactions. The use cases specify what information must pass the boundary of the system in the course of a dialog (without considering what happens inside the system). Because the use cases represent recipes for user achieving goals, each use-case name must include a verb capturing the goal achievement. The key activities are summarized in an artifact called use case diagram. Given the ATM machine example (Figure 1-3), Figure 1-8 illustrates the flow of events for the use case Withdraw Cash. Use cases are only the beginning of a software engineering process. When we draw and elaborate a use case diagram of a system, it signifies that we know what the system needs to accomplish, not how; therefore, it is not just a small matter of system building (programming) that is left after we specify the use cases. Requirements analysis is further detailed in Section 2.2.

Chapter 1

Introduction

13

Enter your PIN

Verify account XYZ

How may I help you?

1 4 2 7 85 6 3 0 9

1 4 2 7 85 6 3 0 9

Typing in PIN number

XYZ valid. Balance: $100

Withdraw $60

Please take your cash

E
4

XYZ withdrew $60

2 5 3 8 6 9

Collecting cash

Acknowledged

Figure 1-8: Scenario for use case Withdraw Cash. Unlike Figure 1-5, this figure only shows interactions of the actors and the system.

1.2.3

Object-Oriented Analysis and the Domain Model

if one wants to understand any complex thingbe it a brain or an automobileone needs to develop good sets of ideas about the relationships among the parts inside. one must study the parts to know the whole. Marvin Minsky, The Emotion Machine

Use cases consider the system as a black box and help us understand how the system as a whole interacts with the outside word. The next step is to model the inside of the system. We do this by building the domain model, which shows what the black box (the system) encloses. Given a service description, we can imagine the process of populating the black box with domain concepts as follows. Notice that while uses cases elaborate the systems behavioral characteristics (sequence of stimulus-response steps), domain model gives details of the systems structural characteristics (system parts and their arrangement). It is useful to consider a metaphor in which software design is seen as creating a virtual enterprise or an agency. The designer is given an enterprises mission description and hiring budget, with the task of hiring appropriate workers, acquiring things, and initiating the enterprises operating process. Unfortunately, what is missing is a list of positions with a job description for each position. The designer needs to identify the positions and the accompanying roles and responsibilities and start filling the positions with the new workers. Recall the ATM machine example from Figure 1-3. We need to identify the relevant players internal to the system (called concepts), as illustrated in Figure 1-7(b).

Ivan Marsic

Rutgers University

14

Imagine you are charged with hiring all people in a newly created enterprise, you are given the description of services the enterprise will offer and the budget for employee salaries. You start with defining what positions should be created and then filling these positions with new employees. In the language of requirements analysis, the enterprise is the system to be developed and the employees are the domain concepts. As you would guess, the key step is to hire the right employees (identify good concepts, or abstractions). Somewhat less critical is to define their relationships and each individuals attributes, and this should be done only for those that are relevant for the task they are assigned to. I like this metaphor of hiring workers because it is in the spirit of what Richard Feynman considered the essence of programming, which is getting something to do something [Feynman et al., 2000]. It also sets up the stage for the important task of assigning responsibilities to software objects. This approach to creating the domain model is somewhat different from that in the current literature, which usually models the entire problem domain (entities that are both external and internal to the planned system). I prefer to identify the actors and other external entities during the requirements analysis phase. During the object-oriented analysis phase, we should is to delimit the domain to what the target system will envelop. I feel that this is a more gradual and intuitive approach. However, I want to emphasize that it is hard to sort out software engineering approaches into right or wrong onesthe developer should settle on the approach that produces best results for him or her. On the downside of this freedom of choice, choices ranging from the dumbest to the smartest options can be defended on the basis of a number of situation-dependent considerations. The idea for conducting object-oriented analysis in analogy to setting up an enterprise came to me by looking at the works of Fritz Kahn. In the early 20th century, Kahn produced a succession of books illustrating the inner workings of the human body, using visual metaphors drawn from industrial society. His illustrations drew a direct functional analogy between human physiology and the operation of contemporary technologiesassembly lines, internal combustion engines, refineries, dynamos, telephones, etc. Kahns work is aptly referred to as illustrating the incomprehendable and I think this greatly captures the task faced by a software analyst. The interested reader should search the web for more information on Kahn. Object-oriented analysis is further detailed in Section 2.4.

1.2.4

Object-Oriented Design

The key activity in the design phase is assigning responsibilities to the software objects. A software application can be seen as a set or community of interacting objects. Each object embodies one or more roles, a role being defined via a set of related responsibilities. Roles, i.e., objects, collaborate to carry out their responsibilities. Our goal is to create a design in which they do it in a most efficient manner. Efficient design contributes to system performance, but no less important contribution is in making the design easier to understand by humans. In the ATM machine example, we came up with one potential solution for step-by-step interactions, as illustrated Figure 1-5. The key question for the designer is: is this the best possible way to assign responsibilities and organize activities of the virtual agents? One could solve the

Chapter 1

Introduction

15

same design problem with a different list of players and different organization of their step-bystep interactions. As one might imagine, there is no known way for exactly measuring the optimality of a design. Therefore, we will have to settle for rules-of-thumb and heuristics in deciding how good a design is. So, what kinds of designs are out there? Two very popular kinds of software designs are what I would call Maurits Escher3 and Rube Goldberg4 designs. Both are fun to look at but have little practical value. Escher designs are impossible to implement in reality. Goldberg designs are highly-complicated contraptions, which solve the problem, but they are very brittle. If anything changes in the underlying assumptions, they fail miserably. Information Design Approaches: http://positiveinteraction.com/carleton/2001Design.ppt * Data-centric: entity-relationship diagram * Object Oriented: class hierarchy * Task Oriented: hierarchical task analysis Merge Tasks and Objects: http://www.cutsys.com/CHI97/Tarby.html Object-oriented design is further detailed in Section 2.5.

Maurits Cornelis Escher (1898-1972) is one of the worlds most famous graphic artists, known for his socalled impossible structures, such as Ascending and Descending, Relativity, his Transformation Prints, such as Metamorphosis I, Metamorphosis II and Metamorphosis III, Sky & Water I or Reptiles. Reuben Lucius Goldberg (Rube Goldberg) (1883-1970) was a Pulitzer Prize winning cartoonist, sculptor, and author. He is best known for his inventionselaborate sets of arms, wheels, gears, handles, cups, and rods, put in motion by balls, canary cages, pails, boots, bathtubs, paddles, and live animalsthat take simple tasks and make them extraordinarily complicated.

Ivan Marsic

Rutgers University

16

Figure 1-9: Example: Formal hedge pruning.

1.2.5

Project Estimation and Product Quality Measurement

I will show, on an example of hedge pruning, how project estimation and product quality measurement work hand in hand with incremental and iterative development. Imagine that you want to earn some extra cash this summer and you respond to an advertisement by a certain Mr. McMansion to prune the hedges around his property (Figure 1-9). You have never done hedge pruning before, so you will need to learn as you go. The first task is to negotiate the compensation and completion date. The simplest way is to make a guess that you can complete the job in two weeks and you ask for a certain hourly wage. Suppose that Mr. McMansion agrees and happily leaves for vacation. After one week, you realize that you are much behind the schedule, so to catch up you lower the quality of your work. After two weeks, the hedges are pruned and Mr. McMansion is back from vacation. He will likely find many problems with your work and may balk at paying for the work done. Now suppose that you employ incremental and iterative hedge pruning. You notice that there are several sections of hedges, labeled with encircled numbers to in Figure 1-9. Think of hedge pruning as traveling along the hedge at a certain velocity (while pruning it). To estimate the travel duration, you need to know the length of the path (or, path size). That is

Travel duration =

Path size Travel velocity

(1.1)

Because you have never pruned hedges, you do not know your velocity, so the best you can do is to guess it. You could measure the path size using a tape measure, but you notice there is a problem. Different sections seem to have varying difficulty of pruning, so your velocity will be

Chapter 1

Introduction

17

different along different sections. For example, section at the corner of Back and Side Streets, seems to be much more difficult to prune than section between the garden and Main Street. Let us assume you assign pruning points to different sections to estimate their size and complexity. Suppose you use the scale from 1 to 10. Because section seems to be the most difficult, so we assign it 10 pruning points. The next two sections in terms of difficulty appear to be and , and relative to section you feel that they are at about 7 pruning points. Next are sections , , and , and you give them 4 pruning points. Finally, section gets 3 pruning points and section gets 2 pruning points. The total for the entire hedge is calculated simply by adding the individual sizes
Total size = (points - for - section i )
i =1 N

(1.2)

Therefore, total for the entire hedge is 10 + 27 + 34 + 3 + 2 = 39 pruning points. This represents your size estimate of the entire hedge. It is very important that this is a relative-size estimate, because it measures how big individual sections are relative to one another. So, a section estimated at four pruning points is expected to take twice as long as a section estimated at two pruning points. be weighted 3.5 points instead of 3? There are How accurate is this estimate? Should section two parts to this question: (a) how accurate is the relative estimate for each section, and (b) is it appropriate to simply add up the individual sizes? As for the former issue, instead of eyeballing the hedges and comparing to one another, you could spend days and count all branches in all sections and arrive at a much more accurate estimate. You could even measure density of branches in individual sections, or their length, or hardness, etc. Obviously, there is a point beyond which only minor improvement in estimation accuracy is brought at a huge cost (known as the law of diminishing returns). Many people agree that the cost-accuracy relationship is exponential (Figure 1-10). It is also interesting to notice that, in the beginning of the curve, we can obtain huge gains in accuracy with modest effort investment. As for the latter issue about equation (1.2), using a linear summation, a key question is if the work on one section is totally independent on the work on another section. The independence is equivalent to assuming that every section will be pruned by a different person and each has equal degree of experience with pruning hedges. I believe there are confounding factors that can affect the accuracy of the estimate. For example, as you progress, you will learn about hedge pruning and become more proficient, so your velocity will increase not because the size of some section became smaller but because you became more proficient. In Section 2.2.2 I will further discuss the issue of linear superposition in the context of software projects estimation.

Ivan Marsic

Rutgers University

18

100%

Estimation accuracy

Estimation cost

Figure 1-10: Exponential cost of estimation. Improving accuracy of estimation beyond a certain point requires huge cost and effort (known as the law of diminishing returns).

All you need now is the velocity estimate, and using equation (1.1) you can give Mr. McMansion the estimate of how long the entire hedge pruning will take. Say you guess your velocity at 5 pruning points per day. Using equation (1.1) you obtain 40/5 = 8 days. You tell Mr. McMansion that your initial estimate is 8 days to finish the work, but you may need to adjust this as you go. is the easiest to prune, so Here comes the power of incremental work. You feel that section you decide to start with section , which is worth 2 pruning points. You find out that it took you almost one entire day to complete section . In other words after the first increment you found that your actual velocity is half of what you originally thought, that is 2.5 pruning points per day. You go to Mr. McMansion and tell him that your new estimate is that it will take you 15 more days (or, 15 + 1 = 16 days total) to complete the work. Notice that you do not need to adjust your size estimate of 39 pruning points, because the relative sizes of hedge sections have not changed! It is important to notice that initially you estimate your velocity, but after the first increment you use the measured velocity to obtain a more accurate estimate of the project duration. You may continue measuring your velocity and re-estimating the total effort duration after each increment, but this probably will not be necessary, because after the first few increments you will obtain an accurate measurement of your pruning velocity. The advantage of incremental work is that you can quickly gain an accurate estimate of the entire effort and do not need to rush in the middle to complete it on time, while sacrificing product quality. Speaking about product quality, next we will see how iterative work helps improve product quality. You may be surprised to find that hedge pruning involves more than simply trimming the shrub. Some of parameters that characterize the quality of hedge pruning are illustrated in Figure 1-11. Suppose that after you completed the first increment (section ), Mr. McMansion can examine the work and decide if you need to iterate and work again on section to fix some deficiencies. It is much more likely that Mr. McMansion will be satisfied with your work if he is continuously consulted then if he simply disappeared to vacation after describing the job requirements. Regardless of how detailed the requirements description, you will inevitably face unanticipated situations and your criteria of hedge esthetics may not match those of Mr. McMansion. This is

Chapter 1

Introduction

19

Good Shape (Low branches get sun)

Poor Shape (Low branches shaded from sun)

Heading back not recommended as it alters the natural shape of the shrub

Remove dead wood Remove water spouts and suckers

Snow accumulates on broad flat tops

Straight lines require more frequent trimming

Peaked and rounded tops hinder snow accumulation

Rounded forms, which follow natures tendency, require less trimming

Figure 1-11: Quality metrics for hedge pruning.

why it is important that the customer remains highly involved throughout the duration of the project, and participates in all important decisions and inspects the quality of work any time a visible progress is made. In summary, we use incremental staging and scheduling strategy to quickly arrive at an effort estimate and to improve the development process quality. We use the iterative, reworkscheduling strategy to improve the product quality. Of course, for both of these strategies it is essential to have good metrics. Project and product metrics are described in Chapter 4. We will also see in Section 2.2.2 how user-story points work similar to hedge-pruning points, and how they can be used to estimate development effort and plan software releases.

I start with describing two case-study examples that will be used throughout to illustrate software development techniques.

1.3 Case Studies

Here I introduce two case studies that will be used in examples throughout the text. I will also present several projects designed for student teams later in Section 1.5.

Ivan Marsic

Rutgers University

20

Both of the case studies (as well as student projects) address relatively complex problems. I favor complex projects, threading throughout the book, rather than simple, unconnected examples, because I feel that the former illustrate better the difficulties and the merits of the solutions. My hope is that by seeing software engineering applied on complex (and realistic) scenarios, the reader will better grasp compromises that must be made both in terms of accuracy and richness of our abstractions. This should become particularly evident in Chapter 3, which deals with modeling of the problem domain and the system under discussion. Before we discuss the case studies, I will briefly introduce a simple diagrammatic technique for representing knowledge about problem domains. Concept maps5 are expressed in terms of concepts and propositions, and are used to represent knowledge, beliefs, feelings, etc. Concepts are defined as apperceived regularities in objects, events, and ideas, designated by a label, such as green, high, acceleration, and confused. A proposition is a basic unit of meaning or expression, which is an expression of the relation among concepts. Here are some example propositions: Living things are composed of cells The program was flaky Ice cube is cold

We can decompose arbitrary sentences into propositions. For example, the sentence My friend is coding a new program can be written as the following propositions Proposition Concept Relation 1. I have 2. friend engages in 3. coding constructs a 4. program is
have I

Concept friend coding program new

friend engages in coding constructs a program

How to construct a concept map? A strategy I found useful starts with listing is all the concepts that you can identify in a given problem domain. Next, new create the table as above, initially leaving the Relation column empty. Then come up with (or consult a domain expert for) the relations among pairs of concepts. Notice that, unlike the simple case shown in the table above, in general case some concepts may be related to several other concepts. Finally, drawing the concept map is easy when the table is completed. We will learn more about propositions and Boolean algebra in Chapter 3. Concept maps are designed for capturing static knowledge and relationships, not sequential procedures. I will use concepts maps in describing the case study problems and they can be a helpful tool is software engineering in general. But obviously we need other types of diagrammatic representations and our main tool will be UML.

A good introduction about concept maps can be found here: http://en.wikipedia.org/wiki/Concept_map. CmapTools (http://cmap.ihmc.us/) is free software that facilitates construction of concept maps.

Chapter 1

Introduction

21

Central Computer

Alarm bell

System
1 2 3 4 5 X Y

Light bulb

Backyard doors: External & Internal lock

Lock

Photosensor

Switch Front doors: External & Internal lock

Figure 1-12: Our first case-study system provides several functions for controlling the home access, such as door lock control, lighting control, and intrusion detection and warning.

1.3.1

Case Study 1: From Home Access Control to Adaptive Homes

Figure 1-12 illustrates our case-study system that is used in the rest of the text to illustrate the software engineering methods. In a basic version, the system offers house access control. The system could be required to authenticate (Are you who you claim to be?) and validate (Are you supposed to be entering this building?) people attempting to enter a building. Along with controlling the locks, the system also turns on the light when you unlock the door. As typical of most software engineering projects, a seemingly innocuous problem actually hides many complexities, which will be revealed as we progress through the development cycle. Figure 1-12 already indicates some of thosefor example, houses usually have more than one lock. Shown are two locks, but there could be additional ones, say for a garage entrance, etc. Additional features, such as intrusion detection further complicate the system. For example, the house could provide you with an email report on security status while you are away on vacation. Police will also attend when they receive notification from a central monitoring station that a monitored system has been activated. False alarms require at least two officers to check on and this is a waste of police resources. Many cities now fine residents for excessive false alarms. Here are some additional features to think about. You could program the system to use timers to turn lights, televisions and sound systems on and off at different times to give your home a lived-in look when you are away. Install motion-detecting outdoor floodlights around your home or automatic announcing of visitors with a chime sound. More gadgets include garage door openers, active badges, and radio-frequency identification (RFID) tags, to detect and track the tenants. Also, the motion sensor outside may turn on the outdoors light even before the user unlocks the door. We could dream up all sorts of services; for example, you may want to be able to open the door for pizza-deliveryman remotely, as you are watching television, by point-andclick remote controls. Moreover, the system may bring up the live video on your TV set from a surveillance camera at the doors.

Ivan Marsic

Rutgers University

22

tenant enters wishes key can be upper bound on failed attempts lock opened causes valid key invalid key may signal burglar launches can be prevented by enforcing

dictionary attack

Figure 1-13: Concept map representing home access control.

Looking at the problem in a broader business context, it is unlikely that all or even the majority of households targeted as potential customers of this system will be computer-savvy enough to maintain the system. Hence, in the age of outsourcing, what better idea than to contract a security company to manage all systems in a given area. This brings a whole new set of problems, because we need to deal with potentially thousands of distributed systems, and at any moment many new users may need to be registered or unregistered with the (centralized?) system. There are problems maintaining a centralized database of peoples access privileges. A key problem is having a permanent, hard-wired connection to the central computer. This sort of network is very expensive, mainly due to the cost of human labor involved in network wiring. This is why, even in the most secure settings, a very tiny fraction of locks tend to be connected. The reader should check for an interesting decentralized solution recently proposed by a software company called CoreStreet (http://www.corestreet.com/). In their proposed solution, the freshest list of privileges spreads by viral propagation [Economist, 2004].

First Iteration: Home Access Control

Our initial goal is only to support the basic door unlocking and locking functions. Although at the first sight these actions appear simple, there are difficulties with both. Figure 1-12 shows the locks connected by wire-lines to a central personal computer. This is not necessarily how we want to solve the problem; rather the PC just illustrates the problem. We need it to manage the users (adding/removing valid users) and any other voluminous data entry, which may be cumbersome from a locks keypad. Using a regular computer keyboard and monitor would be much more user friendly. The connections could be wireless, and moreover, the PC may not even reside in the house. In case of an apartment complex, the PC may be located in the renting office. The first choice is about the user identification. Generally, a person can be identified by one of the following: What you carry on you (physical key or another gadget) What you know (password) Who you are (biometric feature, such as fingerprint, voice, face, or iris)

Chapter 1

Introduction

23

I start with two constraints set for this specific system: (1) user should not need to carry any gadgets for identification; and, (2) the identification mechanism should be cheap. The constraint (1) rules out a door-mounted reader for magnetic strip ID cards or RFID tagsit imposes that the user should either memorize the key (i.e., password) or we should use biometric identification mechanism(s). The constraint (2) rules out expensive biometric identifiers, such as face recognition (see, e.g., http://www.identix.com/ and http://passfaces.com/) or voice recognition (see, e.g., http://www.nuance.com/prodserv/prodverifier.html). There are relatively cheap fingerprint readers (see, e.g., http://www.biometrics-101.com/) and this is an option, but to avoid being led astray by technology details, for now we assume that the user memorizes the key. In other words, at present we do not check the persons true identity (hence, no authentication)as long as they know a valid key, they will be allowed to enter (i.e., validation only). For unlocking, a difficulty is with handling the failed attempts (Figure 1-13). The system must withstand dictionary attacks (i.e., burglars attempting to discover an identification key by systematic trial). Yet it must allow the legitimate user to make mistakes. For locking coupled with light controls, a difficulty is with detecting the daylight: What with a dark and gloomy day, or if the photo sensor ends up in a shade. We could instead use the wallclock time, so the light is always turned on between 7:30 P.M. and 7:30 A.M. In this case, the limits should be adjusted for the seasons, assuming that the clock is automatically adjusted for the time shift. Notice also that we must specify which light should be turned on/off: the one most adjacent to the doors? The one in the hallway? The kitchen light? Or, all lights in the house? Interdependency question: What if the door needs to be locked after the tenant enters the house should the light stay on or should different lights turn on as the tenant moves to different rooms? Also, what if the user is not happy with the systems decision and does opposite of what the system did, e.g., the user turns off the light when the system turned it on? How do these events affect the system functioning, i.e., how to avoid that the system becomes confused after such an event? Figure 1-14 illustrates some of the difficulties in specifying exactly what the user may want from such a system. Let us assume that all we care about is whether the lock is disarmed or armed, so we identify two possible states of the lock: disarmed and armed. The system should normally be in the armed state and disarmed only in the event the user supplies a valid key. To arm the lock, the user should press a button labeled Lock, but to accommodate for forgetful users, the system locks automatically 5 min after being unlocked. If the user needs the door open for a while, they can specify the hold-disarmed-period. As can be observed, even with only two states that can be clearly identified, the rules for transitioning between them can become very complex. I cannot overstate the importance of clearly stating the users goals. The goal state can be articulated as disarmed AND light_on. This state is of necessity temporary, because the door should be locked once the user enters the house and the user may choose to turn off the hallway light and turn on the one in the kitchen, so the end state ends up being armed AND light_off. Moreover, this definition of the goal state appears to be utterly incomplete.

Ivan Marsic

Rutgers University
validKey + holdOpenPeriod / lock validKey / unlock

24

closed

open

pushLockButton / lock timeAfterUnlock = max{ 5min, holdOpenPeriod } / lock

Figure 1-14: System states and transition rules.

Due to the above issues, there are difficulties with unambiguously establishing the action preconditions. Therefore, the execution of the algorithm turns out to be quite complex and eventually we have to rely only on heuristics. Although each individual activity is simple, the combination of all is overwhelming and cannot be entirely solved even with an extremely complex system! Big software systems have too many moving parts to conform to any set of simple percepts. What appeared a simple problem turns out not to have an algorithmic solution, and on the other hand we cannot guarantee that the heuristics will always work, which means that we may end up with an unhappy customer. Note that we only scratched the surface of what appeared a simple problem, and any of the above issues can be further elaborated. The designer may be simply unable to explicitly represent or foresee every detail of the problem. This illustrates the real problem of heuristics: at a certain point the designer/programmer must stop discerning further details and related issues. But, of course, this does not mean that they will not crop up sooner or later and cause the program to fail. And notice that we have not mentioned program bugs, which are easy to sneak-in in a complex program. Anything can happen (and often does).

1.3.2

Case Study 2: Personal Investment Assistant

The way to make money is to buy stock at a low price, then when the price goes up, sell it. If the price doesnt go up, dont buy it. Will Rogers

Financial speculation, ranging from straight gambling and betting to modern trading of financial securities, has always attracted people. For many, the attraction is in what appears to be a promise of wealth without much effort; for most, it is in the promise of a steady retirement income as well as preserving their wealth against worldly uncertainties. Investing in company equities (stocks) has carried the stigma of speculation through much of history. Only relatively recently stocks have been treated as reliable investment vehicles (Figure 1-15). Nowadays, more than 50% of the US households own stocks, either directly, or indirectly through mutual funds, retirement accounts or other managed assets. There are over 600 securities exchanges around the world. Many people have experience with financial securities via pension funds, which today are the largest investor in the stock market. Quite often, these pension funds serve as the interface to the financial markets for individual investors. Since early 1990s the innovations in personal computers and the Internet made possible for the individual investor to enter the stock markets without the help from pension funds and brokerage firms. The Internet also made it possible to do

Chapter 1

Introduction

25

people who trade have expectation of are attracted by hints at markets performance history short-term objectives shows +10% annual returns over long run negative returns 1/3 of the time retirement income is done through is done through broker retirement plan profit returns are needed for can have indirect participation

direct participation

pension fund mutual fund hedge fund

Figure 1-15: Concept map of why people trade and how they do it.

all kinds of researches and comparisons about various companies, in a quick and cheap fashion an arena to which brokerage firms and institutional investors had almost exclusive access owing to their sheer size and money-might. Computers have, in the eyes of some, further reduced the amount of effort needed for participation in financial markets, which will be our key motivation for our second case study: how to increase automation of trading in financial markets for individual investors. Opportunities for automation range from automating the mechanics of trading to analysis of how wise the particular trades appear to be and when risky positions should be abandoned. There are many different financial securities available to investors. Most investment advisers would suggest hedging the risk of investment loss by maintaining a diversified investment portfolio. In addition to stocks, the investor should buy less-risky fixed income securities such as bonds, mutual funds, treasuries bills and notes or simply certificate of deposits. To simplify our case study, I will ignore such prudent advice and assume that our investor wants to invest in stocks only.

Why People Trade and How Financial Markets Work?

Anyone who trades does so with the expectation of making profits. People take risks to gain rewards. Naturally, this immediately begets questions about the kind of return the investor expects to make and the kind of risk they are willing to take. Investors enter into the market with varied objectives. Broadly, the investor objectives could be classified into short-term-gain and long-term-gain. The investors are also of varied types. There are institutional investors working for pension funds or mutual funds, and then there are day-traders and hedge-fund traders who mainly capitalize on the anomalies or the arbitrages that exist in the markets. Usually the institutional investors have a long outlook while the day-traders and the hedge-funds are more prone to have a short take on the market. Here I use the terms trader and investor and synonymous. Some people use these terms to distinguish market participants with varied objectives and investment styles. Hence, an investor is a person with a long outlook, who invests in the company future by buying shares and holds onto them expecting to profit in long term. Conversely, a trader is a person with a short

Ivan Marsic

Rutgers University

26

Trader Market exchange

Broker

Exchange

Brokers Traders/ Investors

Bank

(a)

(b)

Figure 1-16: Structure of securities market. (a) Trading transactions can be executed only via brokers. (b) Block diagram of market interactions.
price quote can be traded price is set by last trade can be buying stock is executed at ask price indicative price can be

selling stock

is executed at

bid price

Figure 1-17: Concept map explaining how quoted stock prices are set.

outlook, who has no long-term interest in the company but only looks to profit from short-term price variations and sells the shares at first such opportunity. As shown in Figure 1-16(a), traders cannot exchange financial securities directly among themselves. The trader only places orders for trading with his or her broker and only accredited financial brokers are allowed to execute transactions. Before the Internet brokers played a more significant role, often provided investment advice in addition to executing transactions, and charged significant commission fees. Nowadays, the discount brokers mostly provide the transaction service at a relatively small commission fee.

Mechanics of Trading in Financial Markets

A market provides a forum where people always sell to the highest bidder. For a market to exist there must be a supply and demand side. As all markets, financial markets operate on a bid-offer basis: every stock has a quoted bid and a quoted ask (or offer). The concept map in Figure 1-17 summarizes how the stock prices function. The trader buys at the current ask and sells at the current bid. The bid is always lower than the ask. The difference between the bid and the ask is referred to as the spread. For example, assume there is a price quote of 100/105. That means the highest price someone is willing to pay to buy is 100 (bid), and the lowest price there is selling

Chapter 1

Introduction

27

interest at 105 (offer or ask). Remember that there are volumes (number of shares) associated with each of those rates as well. Using the bid side for the sake of illustration, assume that the buyer at 100 is willing to purchase 1,000 units. If someone comes in to sell 2,000 units, they would execute the first 1,000 at 100, the bid rate. That leaves 1,000 units still to be sold. The price the seller can get will depend on the depth of the market. It may be that there are other willing buyers at 100, enough to cover the reminder of the order. In an active (or liquid) market this is often the case. What happens in a thin market, though? In such a situation, there may not be a willing buyer at 100. Let us assume a situation illustrated in the table below where the next best bid is by buyer B3 at 99 for 500 units. It is followed by B4 at 98 for 100 units, B1 for 300 units at 97, and B2 for 200 at 95. The trader looking to sell those 1,000 remaining units would have to fill part of the order at 99, more at 98, another bit at 97, and the last 100 at 95. In doing so, that one 2,000 unit trade lowered the bid down five points (because there would be 100 units left on the bid by B2). More than likely, the offer rate would move lower in a corresponding fashion.
Trader Bid Ask Num. of shares

Seller S1 market 1000

Buyer B1 $97 300

Buyer B2 $95 200

Buyer B3 $99 500

Buyer B4 $98 100

The above example is somewhat exaggerated but it illustrates the point. In markets with low volume it is possible for one or more large transactions to have significant impact on prices. This can happen around holidays and other vacation kinds of periods when fewer traders are active, and it can happen in the markets that are thinly traded in the first place. When a trader wishes to execute a trade, he or she places an order, which is a request for a trade yet to be executed. Buy or sell orders differ in terms of the time limit, price limit, discretion of the broker handling the order, and nature of the stock-ownership position (explained below). There are four types of orders that are most common and frequently used: 1. Market order: An order to be executed immediately. The limit here is set, in a way, by the market. A market order to buy 100 shares of Google means buy the stock at whatever the current ask (offer) price is at the time the trade is executed. The trader could pay more than the observed ask price, because the market may have shifted by the time the order is executed (also recall the above example). The ask price used for the execution may be higher or lower than the one observed by the trader. Market orders are the quickest but not necessarily the optimal way to buy or sell a security. 2. Limit order: An order executed at a specific price, or better. The trader using a limit order specifies the maximum buy price or the minimum sale price at which the transaction will be executed. That means when buying it would be at the limit price or below, while the reverse is true for a sell order. For example, a limit order to sell 100 Google shares at 600 means the trade will be executed at or above 600. 3. Stop order: A delayed market order to buy or sell a security when a certain price is reached or passed. A stop order is set at a point above (for a buy) or below (for a sell) the current price. When the current price reaches or passes through the specified level, the stop order is converted into an active market order (defined above in item 1). For

Ivan Marsic

Rutgers University

28

owning stock means long position is exited by selling stock creates profit
profit = salePrice purchasePrice commissions

profits through

stock price appreciation

owning cash earned by selling borrowed stock means short position is exited by buying stock creates profit profits through stock price depreciation

(a)

returning borrowed stock

profit = salePrice purchasePrice loanInterest commissions

trader

expects performs

share price depreciation

1
borrows shares from broker collects are held by

selling borrowed shares generates triggers creates a is executed short position at

sale proceeds commissions interest on loan interest on sale proceeds

3
bid price

is exited by

4
buying shares yields is executed at ask price

are returned to repossessed shares

(b)

Figure 1-18: (a) Concept map of two types of stock-ownership positions: long and short. (b) Concept map explaining how short position functions.

example, a sell stop at 105 would be triggered if the market price touches or falls below 105. 4. Stop Limit Order: A combination of the stop and limit orders. Unlike the simple stop order, which is converted into a market order when a certain price is reached, the stop limit order is converted into a limit order. Hence, the trader will get a fill at or better than the limit order price. There are two types of security-ownership positions: long and short, see Figure 1-18(a). A long position represents actual ownership of the security regardless of whether personal funds, financial leverage (borrowed funds), or both are used in its purchase. Profits are realized if the price of the security increases.

Chapter 1

Introduction

29

A short position involves first a sale of the stock, followed by a purchase at, it is hoped, a lower price, Figure 1-18(b). The trader is short (does not own the stock) and begins by borrowing a stock from the investment broker, who ordinarily holds a substantial number of shares and/or has access to the desired stock from other investment brokers. The trader then sells the borrowed stock at the market price. The short position holder owes the shares to the broker; the short position can be covered by buying back the shares and returning the purchased shares to the broker to settle the loan of shares. This sequence of steps is labeled by numbers in Figure 1-18(b). The trader hopes that the stock price will drop and the difference between the sale price and the purchase price will result in a positive profit. One can argue that there is no such thing as a bad market, there is only the wrong position in the market. If the trader believes that a particular stock will move upwards, he or she should establish a long position. Conversely, if they believe that the stock will slide, they should establish a short position6. The trader can also hedge his or her bets by holding simultaneously both long and short positions on the same stock.

Computerized Support for Individual Investor Trading

Knowing how to place a trading order does not qualify one as a trader. It would be equivalent of saying that one knows how to drive a car just after learning how to use the steering wheel or the brake. There is much more to driving a car than just using the steering wheel or the brake. Similarly, there is much more to trading than just executing trades. To continue with the analogy, we need to have a road map, a travel plan, and we also need to know how to read the road signs. In general, the trader would care to know if a trading opportunity arose and, once he or she places a trading order, to track the status of the order. The help of computer technology was always sought by traders for number crunching and scenario analysis. The basic desire is to be able to tell the future based on the knowledge of the past. Some financial economists view price movements on stock markets as a purely random walk, and believe that the past prices cannot tell us anything useful about price behavior in the future. Others, citing chaos theory, believe that useful regularities can be observed and exploited. Chaos theory states that seemingly random processes may in fact have been generated by a deterministic function that is not random [Bao, Lu, Zhang, 2004]. Bao, Yukun, Yansheng Lu, Jinlong Zhang. Forecasting stock prices by SVMs regression, Artificial Intelligence: Methodology, Systems, and Applications, vol. 3192, 2004. A simple approach is to observe prices pricei(t) of a given stock i over a window of time tcurrent Window, , tcurrent 2, tcurrent 1, tcurrent. We could fit a regression line through the observed points and devise a rule that a positive line slope represents a buying opportunity, negative slope a need to sell, and zero slope calls for no action. Obviously, it is not most profitable to buy when the stock already is gaining nor it is to sell when the stock is already sliding. The worst-case scenario is to buy at a market top or to sell when markets hit bottom. Ideally, we would like to

This is the idea of the so called inverse funds, see more here: B. Steverman: Shorting for the 21st century: Inverse funds allow investors to place bets on predictions of a drop in stocks, Business Week, no. 4065, p. 78, December 31, 2007.

Ivan Marsic

Rutgers University

30

Triangles

?
50 45 40 35 Symmetrical 50 45 40 35 Ascending

?
70 65 60 55 Descending

50 45 40 35
M aj or t

30 25 20 15 Wedge
re nd

30 25 20 15 Flag Pennant

Head Left shoulder Neckline

Right shoulder

Neckline Left shoulder Head

rt jo re nd

Right shoulder Trading volume

a M

Head and Shoulders Bottom

Head and Shoulders Top

Figure 1-19: Technical analysis of stock price trends: Some example types of trend patterns. In all charts the horizontal axis represents time and the vertical axis stock price range. Each vertical bar portrays the high and low prices of a particular stock for a chosen time unit. Source: Alan R. Shaw, Market timing and technical analysis, in Sumner N. Levine (Editor), The Financial Analysts Handbook, Second Edition, pp. 312-372, Dow Jones-Irwin, Inc., Homewood, IL, 1988.

detect the turning points and buy when the price is just about to start rising or sell when the price is just about to start falling. Detecting an ongoing trend is relatively easy; detecting an imminent onset of a new trend is difficult but most desirable. This is where technical analysis comes into picture. Technical analysts believe that market prices exhibit identifiable regularities (or patterns or indicators) that are bound to be repeated. Using technical analysis, various trends could be unearthed from the historical prices of a particular stock and potentially those could be projected into future to have some estimation around where that stock price is heading. Technical analysts believe that graphs give them the ability to form an opinion about any security without following it in real time. They have come up with many types of indicators that can be observed in stock-price time series and various interpretations of the meaning of those indicators. Some chart formations are shown in Figure 1-19. For example, the triangles and flags represent consolidations or corrective moves in market trends. A flag is a well-defined movement contrary to the main trend. The head-and-shoulder formations are used as indicators of trend reversals and can be either top or bottom. In the

Chapter 1

Introduction

31

bottom case, for example, a major market low is flanked on both sides (shoulders) by two higher lows. Cutting across the shoulders is some resistance level called the neckline. (Resistance represents price levels beyond which the market has failed to advance.) It is important to observe the trading volume to confirm the price movements. The increasing volume, as you progress through the pattern from left to right, tells you that more and more traders see the shifting improvement in the companys fortunes. A breakout (a price advance) in this situation signals the end of a downtrend and a new direction in the price trend. Technical analysts usually provide behavioral explanations for the price action and formation of trends and patterns. However, one may wonder if just looking at a sequence of price numbers can tell us everything we need to know about the viability of an investment?! Should we not look for actual causes of price movements? Is the company in bad financial shape? Unable to keep up with competition? Or, is it growing rapidly? There is ample material available to the investor, both, in electronic and in print media, for doing a sound research before making the investment decision. This kind of research is called fundamental analysis, which includes analysis of important characteristics of the company under review, such as: 1. Market share: What is the market standing of the company under review? How much share of the market does it hold? How does that compare against the competitors? 2. Innovations: How is the company fairing in terms of innovations? For example in 3M company no less than 25% of the revenues come from the innovative products of last 5 years. There is even an index for innovations available for review and comparison (8th Jan2007 issue of Business Week could be referred to). 3. Productivity: This relates the input of all the major factors of production money, materials and people to the (inflation adjusted) value of total output of goods and services from the outside 4. Liquidity and Cash-flow: A company can run without profits for long years provided it has enough cash flows, but hardly the reverse is true. A company, if it has a profitable unit, but not enough cash flows, ends of putting that on sale or spinning that unit out. In addition to the above indicators, number crunching is also a useful way to fine-tune the decision. Various financial numbers are readily available online, such as - Sales - EPS: Earning per Share - P/E ttm: Trailing 12 months ratio of Price per Share to that of Earning per Share - P/E forward: Ratio of Estimated Price per Share for coming 12 months to that of Estimated Earning of coming 12 months - ROI: Return on Investment The key barometer of stock market volatility is the Chicago Board Options Exchange's Volatility Index, or VIX, which measures the fluctuations of options contracts based on the S&P 100-stock index.

Ivan Marsic

Rutgers University

32

Traders goal G1: To profit from investment Question: How? Possible answers:

Traders goal G1.1: To identify trading opportunity Question: How? Possible answers:

Traders goal G1.3: To track order status

Traders goal G1.2: To ensure timely & reliable transaction Long-term investors goal G1.2.1: To identify growth/value stock

Short-term traders goal G1.2.2: To identify arbitrage opportunity (indicators in time series)

Figure 1-20: Example of refining the representation of users goals.

In fact, one could argue that the single most important decision an investor can make is to get out of the way of a collapsing market7. Where the investor is usually found to be handicapped is when she enters into the market with the objective of short term gains. The stock market, with its inherent volatility offers ample opportunities to exploit that volatility but what the investor lacks is an appropriate tool to assist in this decision-making process. The investor would ideally like to enter the market after it is open and would exit the market before it is closed, by the end of that day. The investor would seek a particular stock, the price of which she is convinced would rise by the end of the day, would buy it at a lower price and would sell it at a higher price. If she gets inkling, somehow, that a particular stock is going to go up, it will be far easier for her to invest in that stock. Usually time is of essence here and this is where technical analysis comes into picture. Again, we must clearly state what the user needs: the users goals. It is not very helpful to state that the users goal is to make money. We must be as specific as possible, which can be achieved by keeping asking questions How? An example of goal refinement is shown in Figure 1-20. Notice that in answering how to identify a trading opportunity, we also need to know whether our trader has a short-term or long-term outlook to investment. In addition, different trader types may compose differently the same sub-goals (low-level goals) into high-level goals. For example, the long-term investor would primarily consider the companys prospects (G1.2.1), but may employ time-series indicators (G1.2.2) to decide the timing of their investments. Just because one anticipates that an investment will be held for several years because of its underlying fundamentals, that does not mean that he or she should overlook the opportunity for buying at a lower price (near the bottom of an uptrend). It is important to understand the larger context of the problem that we are trying to solve. There are already many people who are trying to forecast financial markets. Companies and governments spend vast quantities of resources attempting to predict financial markets. We have

Michael Mandel, Bubble, bubble, whos in trouble? Business Week, p. 34, June 26, 2006.

Chapter 1

Introduction

33

to be realistic of what we can achieve with relatively minuscule resources and time period of one academic semester. From the universe of possible market data, we have access only to a subset, which is both due to economic (real-time data are available with paid subscription only) and computational (gathering and processing large data quantities requires great computing power) reasons. Assuming we will use freely available data and a modest computing power, the resulting data subset is suitable only for certain purposes. By implication, this limits our target customer and what they can do with the software we are planning to develop. In conclusion, our planned tool is not for a professional trader. This tool is not for institutional investor or large brokerage/financial firm. This tool is for ordinary single investor who does not have acumen of financial concepts, yet would like to leverage the more than average returns that the market offers (especially the year 2006 provided tremendous returns). This tool is for an investor who does not have too much time to do a thorough research on all aspects of a particular company, neither does he have understanding and mastery over financial number crunching. Can it be used for intraday trading? Perhaps not, because real-time price quotations currently are not available for free, this limits the tools usefulness.

1.4 Object Model

You cannot teach beginners top-down programming, because they dont know which end is up. C.A.R. Hoare

An object is a software packaging of data and code together into a unit within a running computer program. Similar to physical objects, software objects, too, have state and behavior. A software object maintains its state in one or more variables. A variable is an item of data named by an identifier. A software object implements its behavior with methods. A method is a function (subroutine) associated with an object. A method can be thought of as a type of interaction with the object. Everything that the software object knows (state) and can do (behavior) is expressed by the variables and the methods within that object. A class is a collection of objects sharing a set of properties that distinguish the objects as members of the collection. Classes are abstractions that specify the state and behavior of different collections of objects. The divide-and-conquer approach goes under different names: reductionism, modularity, structuralism. The object orientation is along the lines of the reductionism paradigm: the tendency to or principle of analysing complex things into simple constituents; the view that a system can be fully understood in terms of its isolated parts, or an idea in terms of simple concepts [Concise Oxford Dictionary, 8th Ed., 1991]. If your car does not work, the mechanic looks for a problem in one of the partsa dead battery, a broken fan belt, or a damaged fuel pump. Reductionism is the idea that the best way to understand any complicated thing is to investigate the nature and workings of each of its parts. This approach is how humans solve problems, and it comprises the very basis of science.

Ivan Marsic

Rutgers University

34

Software Module
Inputs (e.g., force) State (represented by state variables, e.g., momentum, mass, size, ) Outputs (e.g., force)

Software Object
Variables (state)

Methods (behavior)

(a)
Figure 1-21: Software modules (a) vs. software objects (b).

(b)

In classical Newtonian mechanics, the state variables of a physical object are the instantaneous position and momentum, and the future of the system can be determined from those state values. The ability to determine future states depends on being able to observe the instantaneous states and on the knowledge of the dynamics governing state evolution. Modular software design already provides means for breaking software into meaningful components, Figure 1-21. Object oriented approach goes a step further by emphasizing state encapsulation, which means hiding the object state, so that it can be observed or affected only via objects methods. This enables better control over interactions among the modules of an application. Traditional software modules, unlike software objects, are more porous; encapsulation helps prevent leaking of the object state and responsibilities. However, grasping the nature of parts in isolation offers little hint of how they might work in combination. An object may function perfectly when considered alone; however, a combination of two or more may give surprising results. E.g., system enters a deadlock. Or, an object may function fine, but the object which invokes its methods does it in a wrong fashion, yielding wrong results. Thus, a better definition would assert that a system can be fully understood in terms of its parts and the interactions between them. Cf. Newtonian mechanics and the state transitions, knowledge of system dynamics.

1.4.1

Relationships and Communication

There are only two types of relationships in an object model: composition and inheritance. Composition is dynamic, it is defined at run time, during the participating objects lifetimes, and it can change. Inheritance relations are staticthey are defined at the compile time and cannot change for the objects lifetime.

Chapter 1

Introduction

35

elmer.areCoprimes( 905, 1988 )

Prime factorization: 905 = 5 181 1988 = 2 2 7 71

Result: NO!

Stu

Elmer

Figure 1-22: Client object sends a message to a server object by invoking a method on it. Server object is the method receiver.

Software objects work together to carry out the tasks required by the business logic. In objectoriented terminology, objects communicate with each other by sending messages. In the world of software objects, when an object A calls a method on an object B we say, A sends a message to B. In other words, a client object requests the execution of a method from a server object by sending it a message. The message is matched up with a method defined by the class to which the receiving object belongs. Objects can alternate between a client role and a server role. An object is in a client role when it is the originator of an object invocation, no matter whether the objects are located in the same memory space or on different computers. Most objects play both client and server roles. In Figure 1-22, object Stu invokes a method areCoprimes() on the object Elmer to find out if 905 and 1988 are coprimes. Two integers are said to be coprime or relatively prime if they have no common factor other than 1 or, equivalently, if their greatest common divisor is 1. Elmer performs computation and answers negatively. The messages exchanged between the objects are like external forces (in mechanics) or controls (in the control theory sense). A received message may affect the objects state-Because objects work together, as with any organization you would expect that the entities have defined roles and responsibilities. The process of determining what the object should know (state) and what it should do (behavior) is known as assigning the responsibilities. What are objects responsibilities? The responsibilities include: Knowing something (memorization of data or references and providing lookup) Doing something on its own (computation programmed in a method) Asking other objects to do something, saying that does it for me; over to youheres what I did; now its your turn! (communication by sending messages)

Hence, assigning responsibilities essentially means deciding what methods an object gets and who invokes those methods.

Ivan Marsic

Rutgers University

36

(b)
Valid key ? No

Key Key Checker Checker

unlock()

Lock Lock Ctrl Ctrl

turnOn()

Light Light Ctrl Ctrl

(a)

Yes Unlock the lock

unlock()

turnOn() Lock Lock Ctrl Ctrl Light Light Ctrl Ctrl

(c)

Key Key Checker Checker

Turn the light on

Figure 1-23: Comparison of process- and object-based methods on the case study #1 example. (a) A flowchart for a process/procedural programming solution; (b) An objectoriented software solution. (c) An object can be thought of as a person with expertise and responsibilities.

1.4.2

Example

Object-oriented programming then, is describing what messages get exchanged between the objects in the system. This is illustrated on the home access system in our case-study #1 described in Section 1.3.1. The process-based or procedural approach represents solution as a sequence of steps to be followed when the program is executed, Figure 1-23(a). It is a global view of the problem as viewed by the single agent advancing in a stepwise fashion towards the solution. The step-by-step approach is easier to understand when the whole problem is relatively simple and there are few alternative choices along the path. The problem with this approach is when the number of steps and alternatives becomes overwhelming. Object-oriented (OO) approach adopts a local view of the problem. Each object specializes only in a relatively small sub-problem and performs its task upon receiving a message from another object, Figure 1-23(b). Unlike a single agent traversing the entire process, we can think of OO approach as organizing many tiny agents into a bucket brigade, each carrying its task when called upon, Figure 1-23(c). Here are pseudo-Java code snippets for two objects, KeyChecker and LockCtrl:

Listing 1-1: Object-oriented code for classes KeyChecker (left) and LockCtrl (right).
public class KeyChecker { protected LockCtrl lock_; protected java.util.Hashtable validKeys_; ... /** Constructor */ public KeyChecker( LockCtrl lc, ...) { public class LockCtrl { protected boolean state_ = false; // unlocked protected LightCtrl switch_; ... /** Constructor */ public LockCtrl( LightCtrl sw, ...) {

Chapter 1

Introduction

37

lock_ = lc; ... } /** This method waits for and * validates the user-supplied key */ public keyEntered( String key ) { if ( validKeys.containsKey(key) ) { lock_.unlock(id); } } else { // deny access // & sound alarm bell? } } } }

switch_ = sw; ...

/** This method sets the lock * state and handles the switch */ public unlock() { operate the lock device state_ = false; switch_.turnOn(); } public lock(boolean light) { operate the lock device state_ = true; if (light) { switch_.turnOff(); } } }

The key developer skill in object-oriented software development is assigning responsibilities to software objects. Preferably, each object should have only one clearly defined task and that is relatively easy to achieve. The main difficulty in assigning responsibilities arises when an object needs to communicate with other objects in accomplishing a task. When something goes wrong, you want to know where to look or whom to single out. This is particularly important for a complex system, with many functions and interactions. Objectoriented approach is helpful because the responsibilities tend to be known. However, the responsibilities must be assigned adequately in the first place. That is why assigning responsibilities to software objects is probably the most important skill in software development. Some responsibilities are obvious. For example, in Figure 1-23 it is natural to assign the control of the light switch to the LightCtrl object. However, assigning the responsibility of communicating messages is harder. For example, who should send the message to the LightCtrl object to turn the switch on? In Figure 1-23, LockCtrl is charged with this responsibility. Another logical choice is KeyChecker, perhaps even more suitable, because it is the KeyChecker who ascertains the validity of a key and knows whether or not unlocking and lighting actions should be initiated. More details about assigning responsibilities are presented in Section 2.5.

1.4.3

Design of Objects

We separate an objects design into three parts: its public interface, the terms and conditions of use (contracts), and the private details of how it conducts its business. Classes play two roles. First, they act as factories, constructing object instances and implementing responsibilities on their behalf. This role is played by class constructors, which are the blueprints for building instances. Second, they act as an independent service provider, serving client objects in their neighborhood. This role is played by the methods.

Ivan Marsic

Rutgers University

38

OBJECT ORIENTATION

Object orientation is a worldview that emerged in response to real-world problems faced by

software developers. Although it has had many successes and is achieving wide adoption, as with any other worldview, you may question its soundness in the changing landscape of software development. OO stipulates that data and processing be packaged together, data being encapsulated and unreachable for external manipulation other than through objects methods. It may be likened to disposable cameras where film roll (data) is encapsulated within the camera mechanics (processing), or early digital gadgets with a built-in memory. People have not really liked this model, and most devices now come with a replaceable memory card. This would speak against the data hiding and for separation of data and processing. As we will see in Chapter 8, web services are challenging the object-oriented worldview in this sense.

1.5 Student Team Projects

Knowledge must come through action; you can have no test which is not fanciful, save by trial. Sophocles

The book website, given in Preface, describes several student team projects. These projects are selected so each can be accomplished by a team of undergraduate students in the course of one semester. At the same time, the basic version can be extended so to be suitable for graduate courses in software engineering and some of the projects can be extended even to graduate theses. Here I describe only two projects and more projects along with additional information about the projects described here is available at the books website, given in Preface. Each project requires the student to learn one or more technologies specific for that project. In addition, all student teams should obtain a UML diagramming tool.

1.5.1

Stock Market Investment Fantasy League

This project is fashioned after major sports fantasy leagues, but in the stock investment domain. You are to build a website which will allow investor players to make virtual investments in realworld stocks using fantasy money. The system and its context are illustrated in Figure 1-24. Each player has a personal account with fantasy money in it. Initially, the player is given a fixed amount of startup funds. The player uses these funds to virtually buy the stocks. The system then tracks the actual stock movement on real-world exchanges and periodically adjusts the value of players investments. The actual stock prices are retrieved from a third-party source, such as Yahoo! Finance, that monitors stock exchanges and maintains up-to-date stock prices. Given a stock in a players portfolio, if the corresponding actual stock loses value on a real-world stock

Chapter 1

Introduction

39

Stock Market Investment Fantasy League System

Servers and data storage System admin

Web clients Players

Payment system Advertisers

Stock reporting website (e.g., Google/Yahoo! Finance)

Real-world stock exchanges

(e.g., PayPal)

Figure 1-24: Stock market fantasy league system and the context within which it operates.

exchange, the players virtual investment loses value equally. Likewise, if the corresponding actual stock gains value, the players virtual investment grows in the same way. The player can sell the existing stocks or buy new ones at any time. This system does not provide any investment advice. When player sells a stock, his/her account is credited with fantasy money in the amount that corresponds to the current stock price on a stock exchange. A small commission fee is charged on all trading transactions (deducted from the players account). Your business model calls for advertisement revenues to support financially your website. Advertisers who wish to display their products on your website can sign-up at any time and create their account. They can upload/cancel advertisements, check balance due, and make payments (via a third party, e.g., a credit card company or PayPal.com). Every time a player navigates to a new window (within this website), the system randomly selects an advertisement and displays the advertisement banner in the window. At the same time, a small advertisement fee is charged on the advertisers account. A more ambitious version of the system would fetch an advertisement dynamically from the advertisers website, just prior to displaying it. To motivate the players, we consider two mechanisms. One is to remunerate the best players, to increase the incentive to win. For example, once a month you will award 10 % of advertisement profits to the player of the month. The remuneration is conducted via a third party, such as PayPal.com. In addition, the system may support learning by analyzing successful traders and extracting information about their trading strategies. The simplest service may be in the form stock buying recommendations: players who bought this stock also bought these five others. More complex strategy analysis may be devised.

Statement of Requirements
Figure 1-25 shows logical grouping of functions required from our system. Player portfolio consists of positionsindividual stocks owned by the player. Each position should include company name, ticker symbol, the number of shares owned by this player, and date and price when purchased. Player should be able to specify stocks to be tracked without owning any of those stocks. Player should also be able to specify buy- and sell thresholds for

Ivan Marsic

Rutgers University

40

User Functions
Web Client for Players
Registration Account/Portfolio management Trading execution & history Stock browsing/searching Viewing market prices & history

Web Client for Advertisers

Account management Banner uploading and removal Banner placement selection

System Administration Functions

User management Selection of players for awards Dashboard for monitoring the league activities

Backend Operations
Player Management
Account balance Trading support Transactions archiving Portfolio valuation Periodic reporting (email)

Real-World Market Observation & Analysis

Retrieval of stock prices - On-demand vs. periodic Analysis - Technical & fundamental ?

Advertiser Management
Account balance Uploading new banners Banner placement selection

League Management
Player ranking Awards disbursement control Trading performance analysis Coaching of underperformers

Figure 1-25: Logical grouping of required functions for Stock Market Fantasy League.

various stocks; the system should alert (via email) the player if the current price exceeds any of these thresholds. Stock prices should be retrieved periodically to valuate the portfolios and at the moment when the user wishes to trade. Because price retrieval can be highly resource demanding, the developer should consider smart strategies for retrieval. For example, cache management strategies could be employed to prioritize the stocks based on the number of players that own it, the total number of shares owned, etc.

Additional Information
I would strongly encourage the reader to look at Section 1.3.2 for an overview of financial investment. Additional information about this project can be found at the book website, given in Preface. http://finance.yahoo.com/ http://www.marketwatch.com/ See also Problem 2.14 and Problem 2.17 at the end of Chapter 2, the solutions of which can be found at the back of the text.

1.5.2

Web-based Stock Forecasters

Business prophets tell what is going to happen, business profits tell what has happened. Anonymous

Chapter 1

Introduction

41

There are many tools available to investors but none of them removes entirely the element of chance from investment decisions. Large trading organizations can employ sophisticated computer systems and armies of analysts. Our goal is to help the individual investor make better investment decisions. Our system will use the Delphi method,8 which is a systematic interactive forecasting method for obtaining consensus expectation from a panel of independent experts. The goal of this project is to have multiple student teams implement Web services (Chapter 8) for stock-prediction. Each Web service (WS) will track different stocks and, when queried, issue a forecast about the price movement for a given stock. The client module acts as a facilitator which gathers information from multiple Web services (independent experts) and combines their answers into a single recommendation. If different Web services offer conflicting answers, the client may repeat the process of querying and combining the answers until it converges towards the correct answer. There are three aspects of this project that we need to decide on: What kind of information should be considered by each forecaster? (e.g., stock prices, trading volumes, fundamental indicators, general economic indicators, latest news, etc. Stock prices and trading volumes are fast-changing so must be sampled frequently and the fundamental and general-economy indicators are slow-moving so could be sampled at a low frequency.) Who is the target customer? Organization or individual, their time horizon (day trader vs. long-term investor) How the application will be architected? The user will run a client program which will poll the WS-forecasters and present their predictions. Should the client be entirely Web-based vs. locally-run application? A Web-based application would be downloaded over the Web every time the user runs the client; it could be developed using AJAX or a similar technology.

As a start, here are some suggested answers: Our target customers are individuals who are trading moderately frequently (up to several times per week), but not very frequently (several times per day). The following data should be gathered and stored locally. Given a list of about 50100 companies, record their quoted prices and volumes at the maximum available sampling density (check http://finance.yahoo.com/); also record some broad market indices, such as DJIA or S&P500. The gathered data should be used for developing the prediction model, which can be a simple regression-curve fitting, artificial neural network, or some other statistical method. The model should consider both the individual companys data as well as the broad market data. Once ready for use, the prediction model should be activated to look for trends and patterns in stock prices as they are collected in real time.

Potential services that will be provided by the forecaster service include:

An introductory description is available here: http://en.wikipedia.org/wiki/Delphi_method . An in-depth review is available here: http://web.njit.edu/~turoff/Papers/delphi3.html (M. Turoff and S. R. Hiltz: Computer Based Delphi Processes, in M. Adler and E. Ziglio (Editors), Gazing Into the Oracle: The Delphi Method and Its Application to Social Policy and Public Health, London, UK: Kingsley Publishers, 1995.)

Ivan Marsic

Rutgers University

42

Given a stock x, suggest an action, such as buy, sell, hold, or sit-out; we will assume that the forecaster provides recommendation for one stock at a time Recommend a stock to buy, from all stocks that are being tracked, or from all in a given industry/sector

A key step in specifying the forecaster service is to determine its Web service interface: what will go in and what will come out of your planned Web service? Below I list all the possible parameters that I could think of, which the client and the service could exchange. The development team should use their judgment to decide what is reasonable and realistic for their own team to achieve within the course of an academic semester, and select only some of these parameters for their Web service interface.
Parameters sent by the facilitator to a forecaster (from the client to a Web service) in the inquiry include:

Stock(s) to consider: individual (specified by ticker symbol), select-one-for-sector (sector specified by a standard category), any (select the best candidate) Trade to consider: buy, sell, hold, sit-out OR Position to consider: long, short, any

Time horizon for the investment: integer number Funds available: integer number for the capital amount/range Current portfolio (if any) or current position for the specified symbol

Some of these parameters may not be necessary, particularly in the first instantiation of the system. Also, there are privacy issues, particularly with the last two items above, that must be taken into account. The forecaster Web-services are run by third parties and the trader may not wish to disclose such information to third parties.
Results returned by a forecaster to the facilitator (for a single stock per inquiry):

Selected stock (if the inquiry requested selection from sector or any) Prediction: price trend or numeric value at time t in the future Recommended action and position: buy, sell, hold, sit-out, go-short Recommended horizon for the recommended action: time duration Recommendation about placing a protective sell or buy Stop Order. Confidence level (how confident is the forecaster about the prediction): range 0 100 %

The performance of each prediction service should be evaluated as follows. Once activated, each predicted price value should be stored in a local database. At a future time when the actual value becomes known, it should be recorded along with the previously predicted value. A large number of samples should be collected, say over the period of tens of days. We use absolute mean error and average relative error as indices for performance evaluation. The average relative error is defined as i yi yi i yi , where yi and i are the actual and predicted prices at time i,

respectively.

Chapter 1

Introduction

43

Statement of Requirements

Extensions
Risk analysis to analyze what if scenarios. Additional information about this project can be found at the book website, given in Preface.

1.5.3

Remarks about the Projects

My criteria in the selection of these projects was that they are sufficiently complex so to urge the students to enrich their essential skills (creativity, teamwork, communication) and professional skills (administration, leadership, decision, and management abilities when facing risk or uncertainty). In addition, they expose the students to at least one discipline or problem domain in addition to software engineering, as demanded by a labor market of growing complexity, change, and interdisciplinarity. The reader should observe that each project requires some knowledge of the problem domain. Each of the domains has myriads of details and selecting the few that are relevant requires a major effort. Creating a good model of any domain requires skills and expertise and this is characteristic of almost all software engineering projectsin addition to software development skills, you always must learn something else in order to build a software product. The above projects are somewhat deceptive insofar as the reader may get impression that all software engineering projects are well defined and the discovery of what needs to be developed is done by someone else so the developers job is just software development. Unfortunately, that is rarely the case. In most cases the customer has a very vague (or none) idea of what they would like to be developed and the discovery process requires a major effort. That was the case for all of the above projectsit took me a great deal of fieldwork and help from many people to arrive at the project descriptions presented above. In the worst case you may not even know who will be your customer, as is the case for the traffic monitoring (described at the book website, given in Preface) and the investment fantasy league (Section 1.5.1). Frederick Brooks, a major figure in software engineering, wrote that the hardest single part of building a software system is deciding precisely what to build [Brooks, 1995: p. 199]. By this token, the hardest work on these projects is already done. The reader should not feel shortchanged, though, because difficulties in deriving system requirements will be illustrated. The above project descriptions are more precise and include more information than what is usually known as the customer statement of requirements, which is an expression, from a potential customer, of what they require of a new software system. I expressed the requirements more precisely to make them suitable for one-semester (undergraduate) student projects. Our focus here will be on what could be called core software engineering. On the other hand, the methods commonly found in software engineering textbooks would not help you to arrive at the above descriptions. Software engineering usually takes from hereit

Ivan Marsic

Rutgers University

44

assumes a defined problem and focuses on finding a solution. Having defined a problem sets the constraints within which to seek for the solution. If you want to broaden the problem or reframe it, you must go back and do some fieldwork. Suppose you doubt my understanding of financial markets or ability to extract the key aspects of the security trading process (Section 1.3.2) and you want to redefine the problem statement. For that, software engineering methods (to be described in Chapter 2) are not very useful. Rather, you need to employ ethnography or, as an engineer you may prefer Jacksons problem frames [Jackson 2001], see Section 3.3. Do I need to mention that you better become informed about the subject domain? For example, in the case of the financial assistant, the subject domain is finance.

1.6 Summary and Bibliographical Notes

Because software is pure invention, it does not have physical reality to keep it in check. That is, we can build more and more complex systems, and pretend that they simply need a little added debugging. Simple models are important that let us understand the main issues. The search for simplicity is the search for a structure within which the complex becomes transparent. It is important to constantly simplify the structure. Detail must be abstracted away and the underlying structure exposed. Although I emphasized that complex software systems defy simple models, there is an interesting view advocated by Stephen Wolfram in his NKS (New Kind of Science): http://www.wolframscience.com/ , whereby some systems that appear extremely complex can be captured by very simple models.

Although this text is meant as an introduction to software engineering, I focus on critical thinking rather than prescriptions about a structured development process. Software development can by no means be successfully mastered from a single source of instruction. I expect that the reader is already familiar with programming, algorithms, and basic computer architecture. The reader may also wish to start with an introductory book on software engineering, such as [Larman, 2005; Sommerville, 2004]. The Unified Modeling Language (UML) is used extensively in the diagrams, and the reader unfamiliar with UML should consult a text such as [Fowler, 2004]. I also assume solid knowledge of the Java programming language. I do offer a brief introductionto/refresher-of the Java programming language in Appendix A, but the reader lacking in Java knowledge should consult an excellent source by Eckel [2003]. Modular design was first introduced by David Parnas in 1960s. A brief history of object orientation [from Technomanifestos] and of UML, how it came together from 3 amigos. A nice introduction to programming is available in [Boden, 1977, Ch. 1], including the insightful parallels with knitting which demonstrates surprising complexity. Also, from [Petzold] about ALGOL, LISP, PL/I. Objects: http://java.sun.com/docs/books/tutorial/java/concepts/object.html

Chapter 1

Introduction

45

N. Wirth, Good ideas, through the looking glass, IEEE Computer, vol. 39, no. 1, pp. 28-39, January 2006. H. van Vliet, Reflections on software engineering education, IEEE Software, vol. 23, no. 3, pp. 55-61, May-June 2006. [Ince, 1988] provides a popular account of the state-of-the-art of software engineering in mid 1980s. It is worth reading if only for the insight that not much has changed in the last 20 years. The jargon is certainly different and the scale of the programs is significantly larger, but the issues remain the same and the solutions are very similar. Then, the central issues were reuse, end-user programming, promises and perils of formal methods, harnessing the power of hobbyist programmers (today known as open source), and prototyping and unit testing (todays equivalent: agile methods).

The Case Study #1 Project (Section 1.3.1) A path to the future may lead this project to an adaptive house [Mozer, 2004]. See also: Intel: Home sensors could monitor seniors, aid diagnosis (ComputerWorld) http://www.computerworld.com/networkingtopics/networking/story/0,10801,98801,00.html Another place to look is: University of Floridas Gator Tech Smart House [Helal et al., 2005], online at: http://www.harris.cise.ufl.edu/gt.htm For the reader who would like to know more about home access control, a comprehensive, 1400pages two-volume set [Tobias, 2000] discusses all aspects of locks, protective devices, and the methods used to overcome them. For those who like to tinker with electronic gadgets, a great companion is [OSullivan & T. Igoe, 2004]. There are many excellent and/or curious websites related to software engineering, such as: Teaching Software Engineering Lessons from MIT, by Hal Abelson and Philip Greenspun: http://philip.greenspun.com/teaching/teaching-software-engineering Software Architecture by Dewayne E. Perry: http://www.ece.utexas.edu/~perry/work/swa/ Software Engineering Academic Genealogy by Tao Xie: http://www.csc.ncsu.edu/faculty/xie/sefamily.htm

The problem of scheduling construction tasks (Section 1.1) is described in [Goodaire & Parmenter, 2006], in Section 11.5, p. 361. One solution involves first setting posts, then cutting, then nailing, and finally painting. This sequence is shown in Figure 1-1 and completes the job in 11 units of time. There is a second solution that also completes the job in 11 units of time: first cut, then set posts, then nail, and finally paint.

D. Coppit, Implementing large projects in software engineering courses, Computer Science Education, vol. 16, no. 1, pp. 53-73, March 2006. Publisher: Routledge, part of the Taylor & Francis Group

Ivan Marsic

Rutgers University

46

J. S. Prichard, L. A. Bizo, and R. J. Stratford, The educational impact of team-skills training: Preparing students to work in groups, British Journal of Educational Psychology, vol. 76, no. 1, pp. 119-140, March 2006. (downloaded: NIH/Randall/MATERIALS2/)

M. Murray and B. Lonne, An innovative use of the web to build graduate team skills, Teaching in Higher Education, vol. 11, no. 1, pp. 63-77, January 2006. Publisher: Routledge, part of the Taylor & Francis Group

Object-Oriented Software Engineering

Chapter 2

Contents
Conceptual integrity is the most important consideration in system design. Fred Brooks, The Mythical Man-Month

2.1 Software Development Methods

2.1.1 2.1.2 2.1.3 Agile Development 2.1.4

The first issue to face with large-scale product development is the logistics of the development and the management issues. Software product development has some peculiarities not present in other engineering disciplines, mainly because software is abstract as well as more complex and more flexible than any other artifact. These peculiarities will be seen to influence the logistics and management of software development. In the following presentation, I will deemphasize development methodology or structured process of development for the reasons explained later. My main goal is to explain the concepts and describe the tools for software development. These concepts and tools are applicable over many different methodologies. Having learned the concepts and tools, the reader can pick their favorite methodology. The presentation is organized to present the material in a progressively increasing depth. Already, Section 1.2 briefly reviewed the stages of the software engineering lifecycle. Now, the tools and techniques for each stage are detailed in this chapter. System specification is further elaborated in Chapter 3 and software design is elaborated in Chapter 5.

2.2 Requirements Engineering

2.2.1 Types of Requirements 2.2.2 User Stories for Agile Development 2.2.3 Requirements Gathering Strategies

2.3 Use Case Modeling

2.3.1 2.3.2 2.3.3 2.3.4 2.3.5 Actors, Goals, and Sketchy Use Cases System Boundary and Subsystems Detailed Use Case Specification Risk Analysis Why Software Engineering Is Difficult (1)

2.4 Analysis: Building the Domain Model

2.4.1 Identifying Concepts 2.4.2 Concept Associations and Attributes 2.4.3 Contracts: Preconditions and Postconditions

2.5 Design: Assigning Responsibilities

2.5.1 Design Principles for Assigning Responsibilities 2.5.2 Class Diagram 2.5.3 2.5.4 Why Software Engineering Is Difficult (2)

2.6 Software Architecture 2.7 Implementation and Testing

2.7.1 2.7.2 Software Testing

2.8 Summary and Bibliographical Notes Problems

47

Ivan Marsic

Rutgers University

48

2.1 Software Development Methods

Plan, v.t. To bother about the best method of accomplishing an accidental result. Ambrose Bierce, The Devils Dictionary

The goal of software methodologists is to understand how expert developers work and convey this to students. Plus, the hope is that new insights will emerge about how to effectively do product development, so even experts might benefit from learning any applying methodology. The truth is, life cycle methods are rarely followed in real life of peoples own will; those who do are usually forced to follow a certain methodology due to the companys policy in place. Why is it so, if following a method should be a recipe for successful projects? There are several reasons why methodologies are ignored or meet resistance in practice. One reason is that methodology is usually derived from a past experience. But, what worked for me may not work for you. Both developers and projects have different characteristics and it is difficult to generalize across either or both categories. A one-size-fits-all approach simply cannot adequately describe complex human activities, such as software development. In addition, method development takes relatively long time to recognize and extract best practices. By the time a method is mature, the technologies it is based on may become outdated. The method may simply be inappropriate for the new and emerging technologies (for example, Web Services, described in Chapter 8). A development method usually lays out a prescriptive process by mandating a sequence of development tasks. Some methods devise very elaborate processes in which a rigid, documentation-heavy methodology is followed with very detailed specifications. The idea is that the developer(s) should follow each step exactly as predetermined and a successful project will be result. In other words, if the rules are followed, it does not matter who carries them out regardless of the developers knowledge and expertise, a mere method adherence leads to a success. Even if key people leave the project or organization, the project should go on as scheduled because everything is properly documented. However, we experience teaches us that this is not the case. Regardless of how well the system is documented, if key people leave, the project suffers. Recent methods, known as agility, attempt to deemphasize process-driven documentation and detailed specifications. They also take into consideration the number and experience of the people on the development team. The hope with metaphors and analogies is that they will evoke understanding much faster and allow cheap broadening it, based on the existing knowledge. Four major software development methodologies can be classified as: Structured analysis and design (SAD) Object-oriented analysis and design (OOAD) Agile software development (ASD) Aspect-oriented software development (AOSD)

Chapter 2

Object-Oriented Software Engineering

49

The structured analysis and design methodology emerged in the 1970s and introduced functional decomposition and data-flow analysis as key modeling tools. The object-oriented analysis and design methodology emerged in the late 1980s and was widely adopted by the mid 1990s. It introduced use cases and the Unified Modeling Language (UML) as key modeling tools. The ideas of agile software development emerged at the end of 1990s and rapidly gained popularity in the software industry as a lightweight way to develop software. Agile development is reviewed in Section 2.1.1. The aspect-oriented software development methodology emerged in the late1990s. It is not a replacement for any of the other methodologies. Rather, it helps deal with scattered crosscutting concerns. Functional features of a software system could be divided into two categories: (1) core features that provide basic functionality and allow the end-user to achieve specific business goals; and, (2) supplementary features that provide support for entitlements, connectivity, concurrency, system interface, etc. Many of the complementary features can be scattered across the application and tangled with core features, which is why they are called crosscutting concerns. By tangled I mean that these crosscutting concerns are invoked in the context of core features and are part of the affected core functionality. Aspect-oriented software development helps deal with crosscutting concerns in a systematic manner.

2.1.1

Agile Development
People forget how fast you did a jobbut they remember how well you did it. An advertising executive Why do we never have time to do it right, but always have time to do it over? Anonymous

Agility is both a development philosophy and a collection of concepts embedded into development methodologies. An agile approach to development is essentially a results-focused method that iteratively manages changes and risks. It also actively involves customers, making them in effect a part of the development team. Unlike process-driven documentation, it promotes outcome-driven documentation. The emphasis of agile practices is on traveling light, producing only those artifacts (documentation) that are absolutely necessary. The philosophy of the agile approach is formulated by the Manifesto for Agile Software Development (http://agilemanifesto.org/). Agile development evangelists recommend that the development should be incremental and iterative, with quick turnover, and light on documentation. They are believers in perfection being the enemy of innovation. This is all well and fine, but it does not tell us anything about where to start and how to proceed. Selecting a line of attack is a major obstacle, particularly for an inexperienced developer. It appears to me that agile methods, such as extreme programming, change the process (management aspect), but make no difference in the techniques for software development. Agile methods are not meant to entirely replace methodologies such as structured analysis and design, or object-oriented analysis and design. Rather, agile methods are focused on how to run the development process, but so far have contributed few tools for software development. An agiledevelopment tool that I have found particularly useful are user stories, which are intended to represent the system requirements, estimate effort and plan software releases (Section 2.2.2).

Ivan Marsic

Rutgers University

50

One difficulty with product development is that when thinking about a development plan, engineer usually thinks in terms of methodology: what to do first, what next, etc. Naturally, first comes discovery (studying the problem domain and finding out how the problem is solved now and proposing how it can be solved better with the to-be-developed technology); then comes development (designing and implementing the system); lastly, the system is deployed and evaluated. This sequential thinking naturally leads to the waterfall model and heavy documentation. Customer does not see it that way. Customer would rather see some rudimentary functionality soon, and then refinement and extension.
AGILE VS. SLOPPY

I have had students complain that demanding readability, consistency, and completeness in
project reports runs against the spirit of agile development. Some software engineering textbooks insist on showing snapshots of hand drawn UML diagrams, as opposed to neat diagrams created electronically, to emphasize the evanescent nature of designs and the need for dynamic and untidy artifacts. This may work for closely knit teams of professionals, working in adjacent offices exclusively on their project. But, I found it not to be conducive for the purpose of grading student reports: it is very difficult to discern sloppiness from agility and assign grades fairly. Communication, after all, is the key ingredient of teamwork, and communication is not improved if readability, consistency, and completeness of project reports are compromised. I take it that agility means: reduce the amount of documentation but not at the expense of the communicative value of project artifacts. Brevity is a virtue, but we also know that redundancy is the most effective way to protect the message from noise effects. (Of course, you need to know the right type of redundancy!) Agile methodologists do not have much faith in visual representations, so you will find few if any graphics and diagrams in agile software development books. Some authors take the agile principles to the extreme and I would caution against this. I have seen claims that working code is the best documentation of a software product. I can believe that there are people for whom program code is the most comprehensible document, but I believe that most people would disagree. Most people would find easiest to understand carefully designed diagrams with accompanying narrative in a plain natural language. Of course, the drawback is that writing proper documentation takes time, and it is difficult to maintain the documentation consistent with the code as the project progresses. Even greater problem is that code documents only the result of design decisions taken by the developer, but not the reasoning behind those decisions. Code is a solution to a problem. It is neither a description of the problem, nor of the process by which the problem was solved. Much of the rationale behind the solution is irretrievably lost or hidden in the heads of the people who chose them, if they are still around. After a period of time, even the person who made a design decision may have difficulty explaining it if the reasons for the choice are not explicitly documented. However, although documentation is highly desirable it is also costly and difficult to maintain. The developer may even not be aware of some choices that he or she made, because they appear to be common sense. Other decisions may result from companys policies that are documented separately and may be changed independently of the program documentation. It is useful to

Chapter 2

Object-Oriented Software Engineering

51

Aspect-Oriented Requirements

Object-Oriented Analysis & Design Requirements gathering Structured Analysis & Design Requirements analysis Requirements specification

Agile Development User Stories

Figure 2-1: Requirements process in different methodologies.

consider again the exponential curve in Figure 1-10, which can be modified for documentation instead of estimation. Again, a relatively small effort yields significant gains in documentation accuracy. However, after a certain point the law of diminishing returns triggers and any further improvement comes at a great cost. It is practically impossible to achieve perfect documentation.

2.2 Requirements Engineering

The hardest single part of building a software system is deciding what to build. No part of the work so cripples the resulting system if done wrong. No other part is more difficult to rectify later.Fred Brooks You start coding. Ill go find out what they want. Computer analyst to programmer

Requirements engineering helps software engineer to better understand the problem they will work to solve. It involves activities that lead to an understanding of what the customer wants, how end-users will interact with the software, and what the business impact will be. Requirements engineering starts with the problem definition: customer statement of requirements. This is an informal description of what the customers think they need of a software system to do for them. The problem could be identified by management personnel, through market research, by ingenious observation, or some other means. Defining the requirements for the planned system includes both fact-finding about how the problem is solved in the current practice as well as envisioning how the planned system might work. Although different methodologies provide different techniques for requirements engineering, all of them follow the same requirements process: requirements gathering, requirements analysis, and requirements specification (Figure 2-1). This is simply a logical ordering of requirements engineering activities, regardless of the methodology that is used.

Ivan Marsic

Rutgers University

52

Requirements gathering (also known as requirements elicitation) helps the customer to define what is required: what is to be accomplished, how the system will fit into the needs of the business, and how the system will be used on a day-to-day basis. This turns out to be very hard to achieve, as discussed in Section 2.2.3. The customer statement of requirements is rarely clear and complete enough for the development team to start working on the software product. Requirements analysis involves refining and modifying the requirements initially received from the customer during requirements gathering. Analysis is driven by the creation and elaboration of user scenarios that describe how the end-user will interact with the system. Negotiation with the customer will be needed to determine the priorities, what is essential, and when it is required. A popular tool is the use cases (Section 2.3). Requirements specification represents the problem in a semiformal or formal manner to ensure clarity, consistency, and completeness. It describes the function and performance of the planned software system and the constraints that will govern its development. A specification can be a written document, a set of graphical models, a formal mathematical model, a collection of usage scenarios (or, use cases), a prototype, or any combination of these. The developers could use UML or some other symbolic language for this purpose. It is important to ensure that the developers understanding of the problem coincides with the customers understanding of the problem. Of course, logical ordering does not imply that we must achieve perfection in one stage before we progress to the next one. Quite opposite, the best results are achieved by incremental and iterative attention to different stages of the requirements engineering process. This is an important lesson of the agile development philosophy. Traditional prescriptive processes are characterized by their heavy emphasis on getting all the requirements right and written early in the project. Agile projects, on the other hand, acknowledge that it is impossible to identify all the requirements in one pass. Agile software development introduced a light way to model requirements in the form of user stories, which are intended to capture customer needs, and are used to estimate effort and plan releases. User stories will be described in Section 2.2.2.

Statement of Requirements, Case Study 1: Secure Home Access

Here we extract initial requirements for the home access control system from the description given in Section 1.3.1. The statement of requirements is intended to precisely state the capabilities of the system that the customer needs developed.

Chapter 2

Object-Oriented Software Engineering

53

Table 2-1: Requirements for the first case study, safe home access system (see Section 1.3.1). Identifier Requirement

REQ1

The system shall keep the doors locked at all times. Locking the door shall be requested by pressing a dedicated button. When the lock is disarmed, a countdown shall be initiated at the end of which the lock shall be automatically armed (if still disarmed). The system shall unlock the doors when a valid key code is provided. The key validity shall be established by comparing it to a set of known keys. The system shall allow mistakes while entering the key code. However, to withstand dictionary attacks, the number of allowed failed attempts shall be low, say three. The system shall allow adding new authorized persons or removing the existing ones. The system shall maintain a history log of all attempted accesses for later review. The system shall support search and retrieval of the history log by specifying one or several of the following parameters: the time frame, the actor role, the door location, or the event type (unlock, lock, power failure, etc.). This function shall be available over the Web by pointing a browser to a specific URL. The system shall allow filing complaints about suspicious accesses that require further investigation. This function shall be available over the Web.

REQ2 REQ3 REQ4 REQ5 REQ6

REQ7

Table 2-1 contains only a few requirements that appear to be clear at the outset of the project. Software system requirements are usually written in the form of statements The system shall IEEE has published a set of guidelines on how to write software requirements. This document is known as IEEE Standard 830. Some of the requirements in Table 2-1 are somewhat imprecise and will be enhanced later, as we learn more about the problem and about the tools used in solving it. Other requirements may be discovered or the existing ones altered as the development lifecycle progresses.

Statement of Requirements, Case Study 2: Investment Assistant

Here we extract initial requirements for the personal investment assistant system based on the description given in Section 1.3.2. The requirements are shown in Table 2-2. The statement of requirements is only a digest, and the reader should keep in mind that it must be accompanied with a detailed description of customers business practices and rules, such as the market functioning described earlier. Again, the above list contains only a few requirements that appear to be clear at the outset of the project. Other requirements may be discovered or the existing ones enhanced or altered as the development lifecycle progresses.

Ivan Marsic

Rutgers University

54

Table 2-2: Requirements for the second case study, investment assistant (see Section 1.3.2). Identifier Requirement

REQ1

The system shall support registering new investors by providing a real-world email, which shall be external to our website. Required information shall include a unique login ID and a password that conforms to the guidelines, as well as investors first and last name and other demographic information. Upon successful registration, the system shall set up an account with a zero balance for the investor. The system shall support placing Market Orders specified by the action (buy/sell), the stock to trade, and the number of shares. The current indicative (ask/bid) price shall be shown and updated in real time. The system shall also allow specifying the upper/lower bounds of the stock price beyond which the investor does not wish the transaction executed. If the action is to buy, the system shall check that the investor has sufficient funds in his/her account. When the market order matches the current market price, the system shall execute the transaction instantly. It shall then issue a confirmation about the outcome of the transaction (known as order ticket), which contains: the unique ticket number, investors name, stock symbol, number of shares, the traded share price, the new portfolio state, and the investors new account balance. The system shall review the list of pending Stop Orders at specified periods and for each item of the list take one of the following actions: (i) Remove it from the list of pending stop orders if the Stop Order is outdated; declare it a Failed Order and archive as such; (ii) Convert the Stop Order into a Market Order if the Stop Order is valid and the current stock price matches the indicative (bid or ask) price of the order; (iii) Leave untouched if the Stop Order price has not been reached and the order is valid. If either of actions (i) or (ii) is executed, the system shall complete the transaction and notify the trader by email.

REQ2

REQ3

REQ4 REQ5

The system shall continuously gather the time-series of market data (stock prices, trading volumes, etc.) for a set of companies or sectors (the list to be decided). The system shall process the data for two types of information: (i) on-demand user inquiries about technical indicators and company fundamentals (both to be decided), comparisons, future predictions, risk analysis, etc. (ii) in-vigilance watch for trading opportunities or imminent collapses and notify the trader when such events are detected The system shall record the history of users actions for later review.

REQ6

2.2.1

Types of Requirements
The best performance improvement is the transition from the nonworking state to the working state. John Ousterhout

System requirements make explicit the characteristics of the system that is to be developed. Requirements are usually divided into functional and non-functional. Functional requirements determine how the system is expected to behave and what kind of effects it should produce in the application domain.

Chapter 2

Object-Oriented Software Engineering

55

Non-functional requirements describe system properties that do not relate to the system function. An example of a non-functional requirement is: Maintain a persistent data backup, for the cases of power outages. FURPS+ Non-functional (also known as emergent) system properties: Fault-tolerance Usability Reliability Performance Security

Although it may appear easy at first, the distinction between functional and non-functional requirements is often difficult to make. More often than not, these requirements are intertwined and satisfying a non-functional requirement usually necessitates modifications in the system function. The reader should be cautioned against regarding non-functional requirements secondary in importance relative to functional requirements. The satisfaction of non-functional requirements must be as thoroughly and rigorously ensured as is the case for functional requirements. In any case, satisfaction of a requirement comes down to observable effects in the world.

2.2.2

User Stories for Agile Development

A user story is a brief description of a piece of system functionality as viewed by a user. It represents something a user would be likely to do in a single sitting at the computer terminal. User stories are written in a free-form, with no mandatory syntax, but generally they are fitting the form: user-role + capability + business-value Here is an example of a user story for our case study of secure home access:
As a tenant, I can unlock the doors to enter my apartment.
user-role capability business-value

The business-value part is often omitted to maintain the clarity and conciseness of user stories.

Ivan Marsic

Rutgers University

56

Table 2-3: User stories for the first case study, safe home access. Identifier User Story Size

ST-1 ST-2 ST-3 ST-4 ST-5 ST-6 ST-7

As an authorized person (tenant or landlord), I can keep the doors locked at all times. As an authorized person (tenant or landlord), I can lock the doors on demand. The lock should be automatically locked after a defined period of time. As an authorized person (tenant or landlord), I can unlock the doors. (Test: Allow a limited number of mistakes, say three.) As a landlord, I can manage authorized persons. As an authorized person (tenant or landlord), I can view past accesses. As a tenant, I can file complaint about suspicious accesses.

4 points 3 pts 6 pts 9 points 10 pts 6 pts 6 pts

Table 2-3 shows the user stories for our first case study of home access control (Section 1.3.1). If we compare these stories to the requirements derived earlier (Table 2-1), we will find that stories ST-1, ST-2, and ST-3 roughly correspond to requirement REQ-1, story ST-4 corresponds to REQ-2 and REQ-3, and story ST-5 corresponds to REQ-4, etc. Notice, however, that unlike the IEEE-830 statements The system shall , user stories put the user at the center. User stories can be used to estimate effort and plan software releases. The estimation process works very similarly to the example described in Section 1.2.5. Similar to hedge pruning points described in Section 1.2.5, to measure the relative size of the user stories we assign user-story points to each user story. My preliminary estimates of the relative sizes of the user stories on the scale 110 are shown in the rightmost column of Table 2-3. I have to admit that, as I am making these estimates, I do not have much confidence in them. I am very familiar with the home access case study and went many times over the solutions in subsequent chapters. While making the estimates in Table 2-3, I am trying to make a holistic guess, which requires a great deal of subjectivity. It is impossible to hold all those experiences in ones head at once and combine them in a systematic manner. The resulting estimates simply reflect a general feeling about the size of each user story. This may be sufficient to start the project, but I prefer using more structured methods for software size estimation. One such method is based on use case points, described later in Chapter 4. However, more structured methods come at a costthey require time to derive the design details. I recommend that the reader should always be mindful about which part of the exponential curve in Figure 1-10 he or she is operating on. The desired accuracy of the estimate is acceptable only if the effort to achieve it (or, cost) is acceptable, as well. To apply equation (1.1) and estimate the effort (duration) needed to develop the system, we also need to know the development teams velocity. In physics, velocity is defined as the distance an object travels during a unit of time. If in software project estimation size is measured in story points, then the development teams velocity is defined as the number of user-story points that the team can complete per single iteration (the unit of time). In software projects linear sum of sizes for individual user stories is rarely appropriate because of reuse or shared code. Some functionality will be shared by several stories, so adding up sizes for

Chapter 2

Object-Oriented Software Engineering

57

B A

(b)
City C City B B

A City A

(a)

(c)

Figure 2-2: Combining the part sizes illustrated on a highway building example (a). Cities may be connected independently (b), or parts of the product may be reused (c).

individual stories when estimated independently is not appropriate. Let me illustrate on an analogy. Consider you are charged to build highways from city A to cities B and C (Figure 2-2). You eyeball a geographic map of the area and you estimate that the highway AC will be twice longer than the highway AB. So, you estimate the size for the entire effort as 1s + 2s = 3s, where s is a scaling constant. However, upon more careful inspection you figure out that parts of highways to cities B and C can be shared (reused), as illustrated in Figure 2-2(c). If you choose this option, you cannot estimate the total size just by adding the individual sizes (AB + AC). Instead, you need to consider them together. The total effort will be considerably smaller. Reuse is common in software objects (consider how ubiquitous subroutines and libraries are!). Therefore, my concern is that simply adding the story sizes introduces a gross inaccuracy in the overall effort estimation. Recall the exponential relationship of cost and accuracy (Figure 1-10). The reader would be mistaken to assume that reuse always means less work. Considering again the highway analogy, the solution in Figure 2-2(c) may require more effort or cost than the one in Figure 2-2(b). The infrastructure-sharing solution in Figure 2-2(c) requires building highway interchanges and erecting traffic signs. You may wonder, why should anyone bother with reuse if it increases the effort? The reason may be to preserve resources (conserve the land and protect nature), or to make it easier to connect all three cities, or for esthetic reasons, etc. Reducing the developers effort is not always the most important criterion for choosing problem solutions. The customer who is sponsoring the project decides about the priorities. Agile methodologists recommend avoiding dependencies between user stories. High dependencies between stories make story size estimation difficult. (Notice that the assumption is as follows. The individual story sizes are still combined in a linear sum, but the dependencies are tackled by adjusting the individual size estimations.) When dependencies are detected, the developer can try these ways around it: Combine the dependent user stories into one larger but independent story Find a different way of splitting the stories

Ivan Marsic

Rutgers University

58

An expert developer can easily do this. But then, the expert might as well get an accurate effort estimate by pure guessing. The problem is with beginner developers, who need the most a systematic way of estimating the project effort. The beginner may find it difficult to detect and tackle dependencies between user stories. User stories are lightweight compared to use cases (Section 2.3). A user story is an atomic unit for requirements specification in agile methods. There is no further elaboration and user stories do not contain any structure. If a user story is deemed too complex, it is split into several simpler user stories. Unlike this, use cases have an elaborate structure represented by the use case schema (Figure 2-6). If you decide to work with user stories instead of use cases, you will still need some tools for analysis and design. I am not aware of agile-specific tools for analysis and design, so you can work with object-oriented analysis (Section 2.4) and object-oriented design (Section 2.5).

2.2.3

Requirements Gathering Strategies

Everything true is based on need. George Bernard Shaw Well, as the new Hummer H2 ads observe, need is a highly subjective word. Peter Coffee (in 2003)

Requirements for a planned system should be devised based on observing the current practice and interviewing the stakeholders, such as end users, managers, etc. To put it simply, you cant fix it if you dont know whats broken. Structured interviews help in getting an understanding of what stakeholders do, how they might interact with the planned system, and the difficulties that they face with the existing technology. Agile methodologists recommend that the customers or users stay continuously involved throughout the project duration, instead of only providing the requirements initially and waiting for a completed system. (The reader may wish to check again Section 1.2.5 about the benefits of continuous customer involvement.) How to precisely specify what system needs to do is a problem, but sometimes it is even more difficult is to get the customer to say what he or she expects from the system. Gathering domain knowledge by interviews is difficult because domain experts use terminology and jargon specific to their domain that is unfamiliar and hard for an outsider to grasp. While listening to a domain expert talk, a software engineer may find herself thinking These all are words that I know, but together they mean nothing to me. Some things may be so fundamental or seem too obvious to a person doing them habitually, that they think those are not worth mentioning. In addition, it is often difficult for the user to imagine the work with a yet-to-be-built system. People can relatively easily offer suggestions on how to improve the work practices in small ways, but very rarely can they think of great leaps, such as, to change their way of doing business on the Internet before it was around, or to change their way of writing from pen-and-paper when word processors were not around. So, they often cannot tell you what they need or expect from the system. What often happens is that the customer is paralyzed by not knowing what technology could do and the developer is stuck by not knowing what the customer needs to have. Of great help in such situation is having a working instance, a prototype, or performing a so called Wizard-of-Oz experiment with a mock-up system. See also Ch. 2 of Wicked Problemsproblems that cannot be fully defined.

Chapter 2

Object-Oriented Software Engineering

59

A popular technique for functional requirements engineering is the use case modeling, which is described next.

2.3 Use Case Modeling

A use case is a description of how a user will use the planned system to accomplish business goals. As any description, it can be sketchy or it can be very detailed. Both versions (and many degrees of detail in between) have important uses in requirements engineering. It is natural to start with summary descriptions of use cases and gradually progress towards detailed descriptions that thoroughly specify the planned system. Use cases were already introduced in Section 1.2.2 and the current section presents details of use case modeling. We start with summary descriptions of use cases and end with detailed descriptions that represent the specification of the planned system.

2.3.1

Actors, Goals, and Sketchy Use Cases

The consideration of system requirements starts with identifying the entities that will be related to the system under discussion (SuD), the so-called actors.

Actors and Their Goals

An actor is any entity (human, physical object, or another system) external to the system under discussion that interacts with the SuD. The actors have their responsibilities and seek the systems assistance in managing those responsibilities. In our case-study example of secure home access, residents responsibilities are to maintain the home secured and in proper order, as well as seek comfortable living. The property managers responsibilities include keeping track of current and departed residents. Maintenance personnels responsibilities include checks and repairs. There are also some physical devices depicted in Figure 1-12 that are not part of the SuD but interact with it. They also count as actors for our system, as will be seen later. To carry out its responsibility, an actor sets some goals, which are time and context-dependent. For example, a resident leaving the apartment for work has a goal of locking the door; when coming back from work, the residents goal is to open the door and enter the apartment. To achieve its goals, an actor performs some actions. An action is the triggering of an interaction with the SuD. While preparing a response to the actors action, the SuD may need assistance from external entities other than the actor who initiated the process. Recall how in Figure 1-8 the SuD (ATM machine) needed assistance from a remote datacenter to successfully complete the use case Withdraw Cash. This is why we will distinguish initiating actors and participating actors. If the participating actor delivers, then the initiating actor is closer to reaching its goal. All actors should have defined responsibilities. The SuD itself is an actor and its responsibility is to assist

Ivan Marsic

Rutgers University

60

the (initiating) actors in achieving their goals. In this process, SuD may seek help from other systems or (participating) actors. To this point we have identified the following actors: Tenant is the home resident Landlord represents the property management personnel Devices, such as lock-mechanism and light-switch, that are controlled by our system (see Figure 1-12) Other potential actors: Maintenance, Police, etc. (some will be introduced later)

When deciding about the introducing new actors, the key question is: Does the system provide different service(s) to the new actor? It is important to keep in mind that an actor is associated with a role rather than with a person. Hence, a single actor should be created per role, but a person can have multiple roles, which means that a single person can appear as different actors. Also, multiple persons can play the same role, i.e., appear as a single actor, perhaps at different times. In addition, our system may receive assistance from another system in the course of fulfilling the actors goal. In this case, the other system(s) will become different actors if they offer different type of service to our SuD. Examples will be seen later. Table 2-4 summarizes preliminary use cases for our case-study example.
Table 2-4: Actors, goals, and the associated use cases for the home access control system. Actor Actors Goal Use Case Name

Landlord Landlord Landlord Tenant Tenant Tenant LockDevice LightSwitch [to be identified]

To disarm the lock and enter, and get space lighted up. To lock the door & shut the lights (sometimes?). To manage user accounts and maintain the database of residents up to date.

Unlock (UC-1) Lock (UC-2) ManageUsers (UC-3)

To find out who accessed the home in a given interval of InspectAccessHistory time and potentially file complaints. (UC-4) To disarm the lock and enter, and get space lighted up. To lock the door & shut the lights (sometimes?). To control the physical lock mechanism. To control the lightbulb. Unlock (UC-1) Lock (UC-2) UC-1, UC-2 UC-1, UC-2

To auto-lock the door if it is left unlocked for a given AutoLock (UC-2) interval of time.

Because the Tenant and Landlord actors have different responsibilities and goals, they will utilize different use cases and thus they should be seen differently by the system. The new actor can use more (or less, subset or different ones) use cases than the existing actor(s), as seen in Table 2-4. We could distinguish the Maintenance actor who can do everything as the Landlord, except to manage users. If we want to include the Maintenance but the same use cases apply for this actor as for the Tenant, this means that there is no reason to distinguish themwe just must come up with an actor name that covers both.

Chapter 2

Object-Oriented Software Engineering

61

Notice that the last row contains a yet-to-be-identified actor, whose goal is to automatically arm the lock after a certain period of time expires, to account for forgetful persons. Obviously, this is not a persons goal, but neither is it the SuDs goal because SuD does nothing on its ownit must receive an external stimulus to take action. We will see later how this is solved. Generally, the system under development has five key stakeholders: customers, systems and business analysts, systems architects and developers, software testing and quality assurance engineers, and project managers. We will be mainly concerned with the actors that interact directly with the SuD, but any of the stakeholders has certain goals for the SuD and occasionally it may be appropriate to list those goals.

1 2 3 4 5 X Y

To summarize, an actor can be a person or another system which interacts with our SuD. There are two main categories of actors, defined relative to a particular use case: 1. Initiating actor (also called primary actor): initiates the use case to realize a goal, which depends on the actors responsibilities and the current context 2. Participating actor (also called secondary actor): participates in the use case but does not initiate it; two subcategories: (a) Supporting actor: helps the SuD to complete the use casein other words, our SuD acts as a initiating actor of the supporting actor (b) Offstage actor: passively participates in the use case, i.e., neither initiates nor helps complete the use case, but may be notified about some aspect of it Actors may be defined in generalization hierarchies, in which an abstract actor description is shared and augmented by one or more specific actor descriptions. Table 2-4 implies that a software system is developed with a purpose/responsibilitythis purpose is assisting its users (actors) to achieve Tenant Landlord their goals. Use cases are usage scenarios and therefore there must be an actor Actor generalization. intentionally using this system. The issue of developers intentions vs. possible usage scenarios is an important one and can be tricky to resolve. There is a tacit but important assumption made by individual developers and large organizations alike, and that is that they are able to control the types of applications in which their products will ultimately be used. Even a very focused tool is designed not without potential to do other thingsa clever user may come up with unintended uses, whether serendipitously or intentionally.

Resident

Summary Use Cases

A use case is a usage scenario for an external entity, known as actor, and the SuD. A use case represents an activity that an actor can perform on the system and what the system does in response. It describes what happens when an actor disturbs our system from its stationary state as the system goes through its motions until it reaches a new stationary state. It is important to keep in mind that the system is reactive, not proactive; that is, if left undisturbed, the system would remain forever in the equilibrium state.

Ivan Marsic

Rutgers University

62

Table 2-4 names the preliminary use cases for our case-study example. The reader may notice that the summary use cases are similar to user stories (Table 2-3). Like user stories, summary use cases do not describe any details of the business process. They just identify the users role (actor type) and the capability that the SuD will provide (to assist in achieving the actors goals). The same technique for effort estimation that works for user stories (Section 2.2.2) can be applied to summary use cases. We can use again user story points and the development velocity to estimate the project duration by applying equation (1.1), given in Section 1.2.5. Later, in Section 4.2.2, we will describe use case points for software size measurement and effort estimation. However, use case points cannot be applied on summary use cases, because they require detailed use case descriptions. Detailed use case descriptions require time and effort to obtain, so they will become available only at a later stage in the project lifecycle (see Section 2.3.3).

Casual Description of Use Cases

THE TASK-ARTIFACT CYCLE

Use case analysis as well as task analysis (Kirwan & Ainsworth, 1992) emerged in the tradition of mechanization of work and the division of labor pioneered by F. W. Taylor (Kanigel, 2005), which assumes that detailed procedure can be defined for every task. So far we aimed to define the use cases in a technology-independent mannerthe system usage procedure should be independent of the device/artifact that currently implements the use case. However, this is not easy or perhaps even possible to achieve, because the user activities will depend on what steps are assumed to have been automated. For example, the details of the use case UC-1 (Unlock) depend on the user identification technology. If a face-recognition technology were available that automatically recognizes authorized from unauthorized users, then UC-1 becomes trivial and requires no explicit user activities. Consider a simple example of developing a digital wristwatch. For a regular watch, the owner needs to manually adjust time or date when traveling to a different time zone or at the end of a month. Therefore, we need to define the use cases for these activities. On the other hand, if the watch is programmed to know about the owners current GPS location, time zones, calendar, leap years, daylight-saving schedule, etc., and it has high quality hardware, then it needs no buttons at all. Some of this information could be automatically updated if the watch is wirelessly connected to a remote server. This watch would always show the correct time because everything is automated. It has no use cases that are initiated by the human owner, unlike a manually-operated watch. The interested reader should consult (Vicente, 1999: p. 71, 100-106) for further critique of how tasks affect artifacts and vice versa.

Chapter 2

Object-Oriented Software Engineering

63

First tier use cases

participat initiate e

Second tier use cases

UC2: Lock

participate

LockDevice

ini tiat e

Tenant
p
in te itia

ate rticip pa ate particip

initia te

+ pa rticip ate

LightSwitch

UC1: Unlock
inclu de

initiate

Landlord
actor

in itia te

communication use case

Figure 2-3: UML use case diagram for the case-study. Compare with Table 2-4.

Use Case Diagrams

Figure 2-3 sums up the actors, use cases, and their relationships in a so-called use case diagram. There are two use-case categories distinguished: first- vs. second tier. The first tier use cases represent meaningful services provided by the system to an actor. The second tier ones represent elaborations or sub-services of the main services. In a sense, they are equivalent of subroutines in programs because they capture some repetitive activity and can be reused in multiple locations. The figure also shows the relationship of use cases in different tiers. The two stereotypical- or clich types of relationship are: extend alternative actual implementations of the main case include subtasks of the main case

The developer can introduce new stereotypes or clichs for representing the use case relationships. Notice also that the labels on communication lines (initiate and participate) are often omitted to avoid cluttering. The AuthenticateUser use case is not a good candidate for first tier use cases, because it does not represent a meaningful stand-alone goal for an initiating actor. It is, however, useful to show it as a second tier use case, particularly because it reveals which use cases require user authentication. For example, one could argue that Lock does not need authentication, because performing it without authentication does not represent a security threat. Similarly, Disable should not require authentication because that would defeat the purpose of this case. It is of note that these design decisions, such as which use case does or does not require authentication, may need further consideration and justification. The reader should not take these lightly, because each one of them

e at ip tic ar

participate

UC5: AuthenticateUser

Timer
actor

extend

UC6: AddUser

UC3: ManageUsers

exten d

inc lu

de

UC7: RemoveUser

UC4: ShowAccessHistory

include

UC8: Login
system boundary

Ivan Marsic

Rutgers University

64

can have serious consequences, and the reader is well advised to try to come up with scenarios where the above design decisions may not be appropriate.
IS LOGIN A USE CASE?

A novice developer frequently identifies user login as a use case. On the other hand, expert
developers argue that login is not a use case. Recall that use case is motivated by users goal; The user initiates interaction with the system to achieve a certain goal. You are not logging in for the sake of logging inyou are logging in to do some work, and this work is your use case.
BAD:
UC8: Login UC3: ManageUsers UC3: ManageUsers Landlord UC4: ShowAccessHistory Landlord UC4: ShowAccessHistory

GOOD:
inc lude

UC8: Login
lude inc

The reader should not mistake the use case diagram for use cases. The diagram serves only to capture an overview of the system services in a concise visual form. It summarized the system features, if you will, without detailing at all how each feature should operate. Conversely, use cases are text stories that detail exactly what happens when an actor attempts to obtain a given service from the system. A helpful analogy is a books index vs. contents: a table-of-contents or index is certainly useful, but the actual content represents the books main value. Similarly, a use case diagram provides a useful overview index, but you need the actual use cases (contents) to understand what the system does or is supposed to do.

2.3.2

System Boundary and Subsystems

Determining the System Boundary

Unfortunately, there are no firm guidelines of delineating the boundary of the system under development. Drawing the system boundary is a matter of choice. However, once the boundary is drawn, the interactions for all the actors must be shown in use cases in which they interact with the SuD.

Chapter 2

Object-Oriented Software Engineering

65

Case (a):
Local face recognition Local computer Face image Apartment building

Security camera Network Network FaceReco, Ltd.

Case (b):
Remote face recognition

Figure 2-4: Alternative cases of face recognition for the cases study example.

Consider a variation of the home access control system which will be used for an apartment building, or a community of apartment buildings, rather than a single-family home. The management demands user identification based on face recognition, instead of alphanumeric password keys. Roughly speaking, a face recognition system works by taking an image of a persons face (mug shot), compares it with the known faces, and outputs a Boolean result: authorized or unauthorized user. Here are two variations (see Figure 2-4): (a) You procure face recognition software, install it on your local computer, and link it up with a standard relational/SQL database for memorizing the faces of legitimate users. (b) After a preliminary study, you find that maintaining the database of legitimate faces, along with training the recognition system on new faces and unlearning the faces of departed residents, are overly complex and costly. You decide that the face recognition processing should be outsourced to a specialized security company, FaceReco, Ltd. This company specializes in user authentication, but they do not provide any applicationspecific services. Thus, you still need to develop the rest of the access control system. The first task is to identify the actors, so the issue is: Are the new tools (face recognition software and relational database) new actors or they are part of the system and should not be distinguished from the system? In case (a), they are not worth distinguishing, so they are part of the planned system. Although each of these is a complex software system developed by a large organization, as far as we (the developer) are concerned, they are just modules that provide data-storage and user-authentication. Most importantly, they are under our control, so there is nothing special about them as opposed to any other module of the planned system. Therefore, for case (a), everything remains the same as in the original design. The use case diagram is shown in Figure 2-3.

Ivan Marsic

Rutgers University

66

UC3: ManageUsers Landlord

extend extend
inclu de

UC6v2: AddUser UC7v2: RemoveUser UC8: Login

participate

Tenant

initiate init iate p ar tic ip at e e at iti in initiate

UC2: Lock

participate initiate

UC1: Unlock

include

Timer UC5v2: AuthenticateUser

FaceReco, Ltd.

Figure 2-5: Part of the modified use case diagram for case (b). See text for details.

For case (b), a part of the new use case diagram is shown in Figure 2-5 (the rest remains the same as in Figure 2-3). Now we need to distinguish a new actor, the FaceReco Company which provides authentication services. There is a need-to-know that they are part of the process of fulfilling some goal(s) of initiating actors.

Subsystems

Software Architecture

2.3.3

Detailed Use Case Specification

A detailed use case description represents a use case of the system as a sequence of interactions between external entities (actors) and the system (SuD). Detailed use cases are usually written as usage scenarios or scripts, listing a specific sequence of actions and interactions between the actors and the system. For use case scenarios, we will use a stepwise, recipe-like description. A scenario describes in a step-by-step manner activities that an actor does and how the system responds. A scenario is also called a use case instance, in the sense that it represents only one of several possible courses of action for a given use case. Use cases specify what information must pass the boundary of a system when a user or another system interacts with it. We usually first elaborate the normal scenario, also called main success scenario, which assumes that everything goes perfect. Because everything flows straightforward, this scenario usually does not include any conditions or branchingit flows linearly. It is just a causal sequence of action/reaction or stimulus/response pairs. Figure 2-6 shows the use case schema.9

The UML standard does not specify the use case schema, so the format for use cases varies across different textbooks. Even a single author may use additional fields to show other important information, such as non-functional requirements associated with the use case.

Chapter 2

Object-Oriented Software Engineering

67

Use Case UC-#:

Related Requirets: Initiating Actor: Actors Goal: Preconditions: Postconditions:

Name / Identifier

[verb phrase]

List of the requirements that are addressed by this use case Actor who initiates interaction with the system to accomplish a goal Informal description of the initiating actors goal What is assumed about the state of the system before the interaction starts What are the results after the goal is achieved or abandoned; i.e., what must be true about the system at the time the execution of this use case is completed

Participating Actors: Actors that will help achieve the goal or need to know about the outcome

Flow of Events for Main Success Scenario: 1. The initiating actor delivers an action or stimulus to the system (the arrow indicates the direction of interaction, to- or from the system) 2. The systems reaction or response to the stimulus; the system can also send a message to a participating actor, if any 3. Flow of Events for Extensions (Alternate Scenarios): What could go wrong? List the exceptions to the routine and describe how they are handled 1a. For example, actor enters invalid data 2a. For example, power outage, network failure, or requested data unavailable
The arrows on the left indicate the direction of interaction: Actors action; Systems reaction

Figure 2-6: A general schema for UML use cases.

Alternate scenarios or extensions in a use case can result from: Inappropriate data entry, such as the actor making a wrong menu-item choice (other than the one he/she originally intended), or the actor supplies an invalid identification. Systems inability to respond as desired, which can be a temporary condition or the information necessary to formulate the response may never become available.

For each of these cases we must create an alternate scenario that describes what exactly happens in such a case and lists the participating actors. Although we do not know what new uses the user will invent for the system, purposeful development is what governs the system design. For example, attempt to burglarize a home may be a self-contained and meaningful goal for certain types of system users, but this is not what we are designing the system forthis is not a legal use case; rather, this must be anticipated and treated as an exception to a legal use case. A note in passing, the reader should observe that use cases are not specific to the object-oriented approach to software engineering. In fact, they are decidedly process-oriented rather than objectoriented, for they focus on the description of activities. As illustrated in Figure 1-8(a), at this stage we are not seeing any objects; we see the system as a black box and focus on the

Ivan Marsic

Rutgers University

68

interaction protocol between the actor(s) and the black box. Only at the stage of building the domain model we encounter objects, which populate the black box.

Detailed Use Cases

For example, for the use case Unlock, the main success scenario in an abbreviated form may look something like this:

Use Case UC-1:

Related Requiremts: Initiating Actor: Actors Goal: Participating Actors: Preconditions:

Unlock
REQ1, REQ2, REQ3, and REQ5 stated in Table 2-1 Any of: Tenant, Landlord To disarm the lock and enter, and get space lighted up automatically. LockDevice, LightSwitch, Timer The set of valid keys stored in the system database is non-empty. The system always displays the menu of available functions; at the door keypad the menu choices are Lock and Unlock.

Postconditions:

The auto-lock timer has started countdown.

Flow of Events for Main Success Scenario: 1. Tenant/Landlord arrives at the door and selects the menu item Unlock 2. include::AuthenticateUser (UC-5) 3. System (a) signals to the Tenant/Landlord the lock status, e.g., disarmed, (b) signals to LockDevice to disarm the lock, and (c) signals to LightSwitch to turn the light on 4. System signals to the Timer to start the auto-lock timer countdown 5. Tenant/Landlord opens the door, enters the home [and shuts the door and locks]

In step 5 above, the activity of locking the door is in brackets, because this is covered under the use case Lock, and is not of concern in this use case. Of course, we want to ensure that this indeed happens, which is the role of an auto-lock timer, as explained later. In addition, we may want to indicate how is the SuD affected should the door be unlocked manually, using a physical key. Although I do not list the extensions or alternate scenarios in the description of UC-1, normally for each of the steps in the main success scenario, we must consider what could go wrong. For example, In Step 1, the actor may make a wrong menu selection Exceptions during the actor authentication are considered below In Step 5, the actor may be held outside for a while, e.g., greeting a neighbor

For instance, to address the exceptions in Step 5, we may consider installing an infrared beam in the doorway that detects when the person crosses it. Example alternate scenarios are given for the AuthenticateUser and Lock use cases below. In step 2 above, I reuse a subroutine use case, AuthenticateUser, by keyword include, because I anticipate this will occur in other use cases, as well. Here is the main scenario for AuthenticateUser as well as the exceptions, in case something goes wrong:

Chapter 2

Object-Oriented Software Engineering

69

Use Case UC-5:

Related Requirements: Initiating Actor: Actors Goal: Participating Actors: Preconditions: Postconditions:

AuthenticateUser (sub-use case)

REQ2, REQ3 stated in Table 2-1 Any of: Tenant, Landlord To be positively identified by the system (at the door interface). AlarmBell, Police The set of valid keys stored in the system database is non-empty. The counter of authentication attempts equals zero. None worth mentioning.

Flow of Events for Main Success Scenario: 1. System prompts the actor for identification, e.g., alphanumeric key 2. Tenant/Landlord supplies a valid identification key 3. System (a) verifies that the key is valid, and (b) signals to the actor the key validity Flow of Events for Extensions (Alternate Scenarios): 2a. Tenant/Landlord enters an invalid identification key 1. System (a) detects error, (b) marks a failed attempt, and (c) signals to the actor 1a. System (a) detects that the count of failed attempts exceeds the maximum allowed number, (b) signals to sound AlarmBell, and (c) notifies the Police actor of a possible break-in 2. Tenant/Landlord supplies a valid identification key 3. Same as in Step 3 above

When writing a usage scenario, you should focus on what is essential to achieve the initiating actors goal and avoid the details of how this actually happens. Focus on the what and leave out the how for the subsequent stages of the development lifecycle. For example, in Step 2 of the use case AuthenticateUser, I just state that the user should provide identification; I do not detail whether this is done by typing on a keypad, by scanning an RFID tag, or by some biometric technology. Here is the main success scenario for the Lock use case:

Latch bolt

Strike plate

Dead bolt

Use Case UC-2:

Related Requirements: Initiating Actor: Actors Goal: Participating Actors: Preconditions: Postconditions:

Lock
REQ1 and REQ5 stated in Table 2-1 Any of: Tenant, Landlord, or Timer To lock the door & get the lights shut automatically (?) LockDevice, LightSwitch, Timer The system always displays the menu of available functions. The door is closed and lock armed & the auto-lock timer is reset.

Flow of Events for Main Success Scenario: 1. Tenant/Landlord selects the menu item Lock 2. System (a) signals affirmation, e.g., lock armed, (b) signals to LockDevice to arm the lock (if not already armed), (c) signal to Timer to reset the auto-lock counter, and (d) signals to LightSwitch to turn the light off (?)

Ivan Marsic

Rutgers University

70

Flow of Events for Extensions (Alternate Scenarios): 2a. System senses that the door is not closed, so the lock cannot be armed 1. System (a) signals a warning that the door is open, and (b) signal to Timer to start the alarm counter 2. Tenant/Landlord closes the door 3. System (a) senses the closure, (b) signals affirmation to the Tenant/Landlord, (c) signals to LockDevice to arm the lock, (d) signal to Timer to reset the auto-lock counter, and (e) signal to Timer to reset the alarm counter

Notice that in this case, the auto-lock timer appears as both the initiating and participating actor for this use case. (This is also indicated in the use case diagram in Figure 2-3.) This is because if the timeout time expires before the timer is reset, Timer automatically initiates the Lock use case, so it is a initiating actor. Alternatively, if the user locks the door before the timeout expires, the timer will be reset, so it is an offstage actor, as well. I also assume that a single Timer system can handle multiple concurrent requests. In the Lock use case, the timer may be counting down the time since the lock has been disarmed. At the same time, the system may sense that the door is not closed, so it may start the alarm timer. If the door is not shut within a given interval, the system activates the AlarmBell actor and may notify the Police actor. You may wonder why not just say that the system will somehow handle the auto-lock functionality rather than going into the details of how it works. Technically, the timer is part of the planned SuD, so why should it be declared an external actor?! Recall that the SuD is always passiveit reacts to an external stimulus but does nothing on its own initiative. Thus, to get the system perform auto-lock, somebody or something must trigger it to do so. This is the responsibility of Timer. Timer is an external stimulus source relative to the software under development, although it will be part of the end hardware-plus-software system. Next follows the description of the ManageUsers use case:

Use Case UC-3:

Related Requirements: Initiating Actor: Actors Goal: Participating Actors: Preconditions: Postconditions:

ManageUsers
REQ4 stated in Table 2-1 Landlord To register new residents and/or remove the departed ones. Tenant None worth mentioning. (But note that this use case is only available on the main computer and not at the door keypad.) The modified data is stored into the database.

Flow of Events for Main Success Scenario: 1. Landlord selects the menu item ManageUsers 2. Landlord identification: Include Login (UC-8) 3. System (a) displays the options of activities available to the Landlord (including Add User and Remove User), and (b) prompts the Landlord to make selection 4. Landlord selects the activity, such as Add User, and enters the new data 5. System (a) stores the new data on a persistent storage, and (b) signals completion

Chapter 2

Object-Oriented Software Engineering

71

Flow of Events for Extensions (Alternate Scenarios): 4a. Selected activity entails adding new users: Include AddUser (UC-6) 4b. Selected activity entails removing users: Include RemoveUser (UC-7)

The Tenant is a supporting actor for this use case, because the tenant will input his or her identification (password or a biometric print) during the registration process. Notice that in UC-3 I include the subordinate use case Login, which is not the same as AuthenticateUser, numbered UC-5. The reason is that UC-5 is designed to authenticate persons at the entrance(s). Conversely, user management is always done from the central computer, so we need to design an entirely different use case. The detailed description of the use case AddUser will be given in Problem 2.10 and RemoveUser is similar to it. In Table 2-4 we introduced UC-4: Inspect Access History, which roughly addresses REQ6 and REQ7 in Table 2-1. I will keep it as a single use case, although it is relatively complex and the reader may wish to split it into two simpler use cases. Here is the description of use case UC-4:

Use Case UC-4: Initiating Actor: Actors Goal: Participating Actors: Preconditions: Postconditions:

Inspect Access History

Related Requirements: REQ5, REQ6, and REQ7 stated in Table 2-1

Any of: Tenant, Landlord To examine the access history for a particular door. Database, Landlord
Tenant/Landlord is currently logged in the system and is shown a hyperlink View Access History.

None.

Flow of Events for Main Success Scenario: 1. Tenant/Landlord clicks the hyperlink View Access History 2. System prompts for the search criteria (e.g., time frame, door location, actor role, event type, etc.) or Show all 3. Tenant/Landlord specifies the search criteria and submits 4. System prepares a database query that best matches the actors search criteria and retrieves the records from the Database 5. Database returns the matching records 6. System (a) additionally filters the retrieved records to match the actors search criteria; (b) renders the remaining records for display; and (c) shows the result for Tenant/Landlords consideration 7. Tenant/Landlord browses, selects interesting records (if any), and requests further investigation (with an accompanying complaint description) 8. System (a) displays only the selected records and confirms the request; (b) archives the request in the Database and assigns it a tracking number; (c) notifies Landlord about the request; and (d) informs Tenant/Landlord about the tracking number

Ivan Marsic

Rutgers University

72

System Sequence Diagrams

A system sequence diagram represents in a visual form a usage scenario that an actor experiences while trying to obtain a service from the system. In a way, they summarize textual description of the use case scenarios. As noted, a use case may have different scenarios, the main success scenario and the alternate ones. A system sequence diagram may represent one of those scenarios in entirety, or a subpart of a scenario. Figure 2-7 shows two examples for the Unlock use case. The key purpose of system sequence diagrams (as is the case with use cases) is to represent what information must pass the system boundary and in what sequence. Therefore, a system sequence diagram can contain only a single box, named System, in the top row, which is our system under discussion (SuD). All other entities must be actors. At this stage of the development cycle, the system is still considered atomic and must not be decomposed into its constituent parts. It may appear that we are peering inside the black box when stating what system does internally during the actor system exchanges. But, notice that we are specifying the what that the black box does, not how this gets done.

Chapter 2

Object-Oriented Software Engineering

73

User

: System

LockDevice

LightSwitch

Timer
offstage actor

initiating actor select function(unlock") prompt for the key

supporting actor supporting actor

(a)

enter key

verify key

signal: valid key, lock open open the lock turn on the light start ("duration)

User

: System

AlarmBell
supporting actor

Police
offstage actor

initiating actor select function(unlock") loop prompt for the key enter key

(b)

verify key

signal: invalid key prompt to try again sound alarm notify intrusion

Figure 2-7: UML System sequence diagrams for the Unlock use case: (a) main success scenario; (b) burglary attempt scenario. The diagram in (b) shows UML loop interaction frame, which delineates a fragment that may execute multiple times.

Activity Diagrams

Use Cases for Requirements Engineering

Use cases are a popular tool for gathering requirements and specifying system behavior. However, I do not want to leave the reader with an illusion that use cases are the ultimate solution for requirements analysis. As any other tool, they have both virtues and shortcomings. I hope that the reader experienced some virtues from the preceding presentation. On the shortcomings side, the suitability of use cases for gathering requirements may be questioned because you start writing the use cases given the requirements. Also, use cases are not equally suitable for all

Ivan Marsic

Rutgers University

74

problems. Considering the projects defined in Section 1.5 and the book website (given in Preface), use cases seem to be suitable for the restaurant automation project. In general, the use case approach is best suited for the reactive and interactive systems. However, they do not adequately capture activities for systems that are heavily algorithm-driven, such as the virtual biology lab and financial markets simulation (both described at the book website, given in Preface), or data-intensive, such as databases or large data collections. Some alternative or complementary techniques are described in Chapter 3.

2.3.4

Risk Analysis and Reduction

Identifying and preempting the serious risks that will be faced by the system is important for any software system, not only for the ones that work in critical settings, such as hospitals, etc. Potential risks depend on the environment in which the system is to be used. The root causes and potential consequences of the risks should be analyzed, and reduction or elimination strategies devised. Some risks are intolerable while others may be acceptable and should be reduced only if economically viable. Between these extremes are risks that have to be tolerated only because their reduction is impractical or grossly expensive. In such cases the probability of an accident arising because of the hazard should be made as low as reasonably practical (ALARP).
Risk Identification Lock left disarmed (when it should be armed) Lock does not disarm (faulty mechanism) Risk Type Intolerable ALARP Risk Reduction Strategy Auto-lock after x minutes Allow physical key use as alternative

To address the intolerable risk, we can design an automatic locking system which observes the lock and auto-locks it after x minutes elapses. This system should be stand-alone, so its failure probability is independent of the main system. For example, it could run in a different runtime environment, such as separate Java virtual machines, or even on an independent hardware. To ensure fault tolerance, a stand-alone system should monitor the state-variable values and prohibit the values out of the safe range, e.g., by overwriting the illegal value. Ideally, a different backup system should be designed for each state variable. This mechanism can work even if it is unknown which part of the main program is faulty and causes the illegal value to occur. A positive aspect of a stand-alone, one-task-only system is its simplicity and lack of dependencies, inherent in the main system, which makes it resilient; a negative aspect is that the lack of dependencies makes it myopic, not much aware of its environment and unable to respond in sophisticated manner.

2.3.5

Why Software Engineering Is Difficult (1)

Disciplined development

A key reason, probably the most important one, is that we usually know only approximately what we are to do. But, a general understanding of the problem is not enough for success. We must know exactly what to do because programming does not admit vaguenessit is a very explicit and precise activity.

Idea SOFTWARE ENGINEERING

Product

Chapter 2

Object-Oriented Software Engineering

75

History shows that projects succeed more often when requirements are well managed. Requirements provide the basis for agreement with the users and the customer, and they serve as the foundation for the work of the development team. This means that requirements provide a vital linkage to ensure that teams deliver systems that solve real business problems. When faced with a difficult decision, it is a good idea to ask the customer for help. After all, the customer can judge best what solution will work best for them and they will easier accept compromises if they were involved in making them. However, this is not always simple. Consider the projects described at the book website (given in Preface). Asking the customer works fine in the restaurant automation project. Even in the virtual biology lab, we can interview a biology course instructor to help with clarifying the important aspects of cell biology. However, who is your customer in the cases of vehicle traffic monitoring and stock investment fantasy league (Section 1.5.1)? As discussed in the description of the traffic-monitoring project, we are not even sure whom the system should be targeted to. More about requirements engineering and system specification can be found in Chapter 3.

2.4 Analysis: Building the Domain Model

Half the work that is done in this world is to make things appear what they are not. Elias Root Beadle

Use cases looked at the systems environment (actors) and the systems external behavior. Now we turn to consider the inside of the system. This shift of focus is contrasted in Figure 2-8. In Section 1.2.3 I likened object-oriented analysis to setting up an enterprise. The analysis phase is concerned with the what aspectidentifying what workers we need to hire and what things to acquire. The design, to be considered later in Section 2.5, deals with the how aspecthow these workers interact with each other and with the things at their workplace to accomplish their share in the process of fulfilling a service request. Of course, as any manager would tell you, it is difficult to make a clear boundary between the what and the how. We should not be purists about thisthe distinction is primarily to indicate where the emphasis should be during each stage of development. We already encountered concepts and their relations in Section 1.3 when describing concept maps as a diagrammatic representation of knowledge about problem domains. Domain model described here is similar to a concept map, although somewhat more complex, as will become apparent soon.

Ivan Marsic

Rutgers University

76

(a)
System

(b)
Domain Model
Concept 3 Concept 1

Concept n
1
7
4
0 5

2
9

Actor Actor
(Remote datacenter)

Concept 2

Actor
(Bank customer)
(AT Mm a ch ine )

Actor

Figure 2-8: (a) Use case model sees the system as a black box. (b) Domain model peers inside the box to uncover the constituent entities and their (static) relations.

2.4.1

Identifying Concepts

Back to our setting-up-an-enterprise approach, we need to hire workers with appropriate expertise and acquire things they will work with. To announce the openings under a classifieds section, we start by listing the positions or, better, responsibilities, for which we are hiring. We identify the responsibilities by examining the use case scenarios and system sequence diagrams. For example, we need a worker to verify whether or not the key entered by the user is valid, so we title this position KeyChecker. We also need a worker to know (memorize, or keep track of) the collection of valid keys, so we advertise an opening for KeyStorage. Further, to operate the lock and the light/switch, we come up with LockOperator and LightOperator positions, respectively. Notice that concept name is always a noun phrase. In building the domain model, a useful strategy is to start from the periphery (or boundary) of the system, as illustrated in Figure 2-9. That is, we start by assigning concepts that handle interactions between the organization and the outside world, that is, between the actors and the system. Each actor interacts with at least one boundary object. The boundary object collects the information from the actor and translates it into a form that can be used by internal objects. As well, the boundary object may translate the information in the other direction, from internal objects to a format suitable for an actor. Organizations are often fronted by a point-of-contact person. A common pattern is to have a specialized worker to take orders from the clients and orchestrate the workings of the workers inside the system. This type of object is known as Controller. For a complex system, each use case or a logical group of use cases may be assigned a different Controller object.

Chapter 2

Object-Oriented Software Engineering

77

Step 1: Identifying the boundary concepts

Boundary concepts
Concept 1 Concept 3

Step 2: Identifying the internal concepts

Concept 3 Concept 1

Actor C Actor A Actor A

Concept 5 Concept 6

Actor C

Concept 2

Concept 4

Concept 2

Internal concepts
Concept 4

Actor B

Actor D

Actor B

Actor D

Figure 2-9: A useful strategy for building a domain model is to start with the boundary concepts that interact directly with the actors (Step 1), and then identify the internal concepts (Step 2).

When identifying positions, remember that no task is too smallif it needs to be done, it must be mentioned explicitly and somebody should be given the task responsibility. Table 2-5 lists the responsibilities and the worker titles (concept names) to whom the responsibilities are assigned. In this case, it happens that a single responsibility is assigned to a single worker, but this is not necessarily the case. Complex responsibilities may be assigned to multiple workers and vice versa a single worker may be assigned multiple simple responsibilities. Further discussion of this issue is available in the solution of Problem 2.14 at the end of this chapter.
Table 2-5: Responsibility descriptions for the home access case study used to identify the concepts for the domain model. Types D and K denote doing vs. knowing responsibilities, respectively. Responsibility Description Typ Concept Name Coordinate actions of all concepts associated with a use case, a logical D Controller grouping of use cases, or the entire system and delegate the work to other concepts. Container for users authentication data, such as pass-code, timestamp, K Key door identification, etc. Verify whether or not the key-code entered by the user is valid. D KeyChecker Container for the collection of valid keys associated with doors and users. K KeyStorage Operate the lock device to armed/disarmed positions. D LockOperator Operate the light switch to turn the light on/off. D LightOperator Operate the alarm bell to signal possible break-ins. D AlarmOperator Log all interactions with the system in persistent storage. D Logger

Based on Table 2-5 we draw a draft domain model for our case-study #1 in Figure 2-10. During analysis, objects are used only to represent possible system state; no effort is made to describe how they behave. It is the task of design (Section 2.5) to determine how the behavior of the system is to be realized in terms of the behavior of objects. For this reason, objects at analysis time have no methods/operations (as seen in Figure 2-10).

Ivan Marsic

Rutgers University

78

Reading direction arrow. Has no meaning; it only facilitates reading the association label, and is often left out. Symbolizes worker-type concept. entity Key control Controller obtains userIdentityCode timestamp doorLocation

Symbolizes thing-type concept.

entity KeyStorage

conveysRequests

boundary KeycodeEntry

Association name

s ifie ver

retrie

eys alidK vesV

boundary StatusDisplay

boundary LockOperator notifiesKeyValidity lockStatus

LockDevice

entity KeyChecker numOfTrials maxNumOfTrials notifiesKeyValidity

Resident

boundary LightOperator lightStatus

LightSwitch

Figure 2-10: Domain model for the case study #1, home access control.

UML does not have designated symbols for domain concepts, so it is usual to adopt the symbols that are used for software classes. I added a smiley face or a document symbol to distinguish worker vs. thing concepts. Workers get assigned mainly doing responsibilities, while things get assigned mainly knowing responsibilities. This labeling serves only as a scaffolding, to aid the analyst in the process of identifying concepts. The distinction may not always be clear cut, because some concepts may combine both knowing- and doing types of responsibilities. In such cases, the concepts should be left unlabeled. This is the case for KeycodeEntry and StatusDisplay in Figure 2-10. Like a real-world scaffolding, which is discarded once construction is completed, this scaffolding is also temporary in nature. Another useful kind of scaffolding is classifying concepts into the following three categories: boundary, control, and entity. This is also shown in Figure 2-10. At first, Key may be considered a boundary because keys are exchanged between the actors and the system. On the other hand, keys are also stored in KeyStorage. This particular concept corresponds to neither one of those, because it contains other information, such as timestamp and the door identifier. Only pass-codes identifying the actors are exchanged between the actors and the system (concept: KeycodeEntry) and this information is transferred to the Key concept. Responsibilities for use case UC-4: Inspect Access History can be derived based on the detailed description of UC-4 (Section 2.3.3). We can gather the doing (D) and knowing (K) responsibilities as given in Table 2-6.
Table 2-6: Responsibility descriptions for UC-4: Inspect Access History of the home access case study. Responsibility Description Rs1. Coordinate actions of concepts associated with this use case and delegate the work to other concepts. Rs2. Form specifying the search parameters for database log retrieval Type Concept Name

D K

Controller Search Request

Chapter 2

Object-Oriented Software Engineering

79

(from UC-4, Step 2). Rs3. Render the retrieved records into an HTML document for sending to actors Web browser for display. Rs4. HTML document that shows the actor the current context, what actions can be done, and outcomes of the previous actions. Rs5. Prepare a database query that best matches the actors search criteria and retrieve the records from the database (from UC-4, Step 4). Rs6. Filter the retrieved records to match the actors search criteria (from UC-4, Step 6). Rs7. List of interesting records for further investigation, complaint description, and the tracking number. Rs8. Archive the request in the database and assign it a tracking number (from UC-4, Step 8). Rs9. Notify Landlord about the request (from UC-4, Step 8).

D K D D K D D

Page Maker Interface Page Database Proxy Postprocessor Investigation Request Archiver Notifier

Note that upon careful examination we may conclude that responsibility Rs6 is relatively simple and it should be assigned to the Page Maker (Postprocessor concept would be rejected). Similarly, responsibilities Rs8 and Rs9 may be deemed relatively simple and assigned to a single concept Archiver (Notifier concept would be rejected). Let us assume that we reject Postprocessor and keep Notifier because it may need to send followup notifications. The partial domain model corresponding to UC-4 is shown in Figure 2-11.

It is worth noticing at this point how an artifact from one phase directly feeds into the subsequent phase. We have use case scenarios feed into the system sequence diagrams, which in turn feed into the domain model. This is a critical property of a good development method (process), because the design elaboration progresses systematically, without great leaps that are difficult to grasp and/or follow. Domain model is similar to a concept map (described in Section 1.3)it also represents concepts

control Controller boundary SearchRequest receives userID searchParams conveysRequests

conveysRequests

entity Archiver currentTrackNum

generates

entity InvestigationRequest recordsList complaintDescr trackingNum

requestsNotify

posts boundary InterfacePage prepares

boundary Notifier requestsSave conveysRequests contactInfo

Landlord

entity PageMaker

Resident

providesData

boundary DatabaseProxy

Database

Figure 2-11: The domain model for UC-4: Inspect Access History of home access control.

Ivan Marsic

Rutgers University

80

boundary HouseholdDeviceOperator deviceStatus

boundary LockOperator

boundary LightOperator

boundary AlarmOperator

Figure 2-12: Generalization of concepts in Figure 2-10. HouseholdDeviceOperator is a conceptual superclass obtained by identifying commonality among the concepts that operate different household devices.

and their relations, here called associationsbut domain model is a bit more complex. It can indicate the concepts stereotype as well as its attributes (described in the next section). Notice that we construct a single domain model for the whole system. The domain model is obtained by examining different use case scenarios, but they all end up contributing concepts to the single domain model.

2.4.2

Concept Associations and Attributes

Associations
Associations (describe who needs to work together and why, not how they work together). Associations for use case UC-4: Inspect Access History can be derived based on the detailed description of UC-4 (Section 2.3.3).
Table 2-7: Identifying associations for use case UC-4: Inspect Access History. Concept pair Controller Page Maker Page Maker Database Proxy Page Maker Interface Page Controller Database Proxy Association description Controller passes requests to Page Maker and receives back pages prepared for displaying Database Proxy passes the retrieved data to Page Maker to render them for display Association name

conveys requests provides data prepares conveys requests conveys requests generates requests save requests notify

Page Maker prepares the Interface Page Controller passes search requests to Database Proxy Controller passes a list of interesting records and complaint description to Archiver, which assigns the tracking number and creates Investigation Request

Controller Archiver

Archiver Archiver generates Investigation Request Investigation Request Archiver requests Database Proxy to store Archiver investigation requests into the database Database Proxy Archiver requests Notifier to notify Landlord about Archiver Notifier investigation requests

Chapter 2

Object-Oriented Software Engineering

81

Figure 2-10 and Figure 2-11 also show the associations between the concepts, represented as lines connecting the concepts. Each line also has the name of the association and sometimes an optional reading direction arrow is shown as . The labels on the association links do not signify the function calls; you could think of these as just indicating that there is some collaboration anticipated between the linked concepts. It is as if to know whether person X and person Y collaborate, so they can be seated in adjacent cubicles/offices. Similarly, if objects are associated, they logically belong to the same package. The reader should keep in mind that it is more important to identify the domain concepts than their associations (and attributes, described below). Every concept that the designer can discover should be mentioned. Conversely, for an association (or attribute), in order to be shown it should pass the does it need to be mentioned? test. If the association in question is obvious, it should be omitted from the domain model. For example, in Figure 2-10, the association Controller obtainsKey is fairly redundant. Several other associations could as well be omitted, because the reader can easily infer them, and this should be done particularly in schematics that are about to become cluttered. Remember, clarity should be preferred to accurateness, and, if the designer is not sure, some of these can be mentioned in the text accompanying the schematic, rather than drawn in the schematic itself.

Attributes
The domain model may also include concept attributes, as is for example shown in Figure 2-10. Example attributes are lockStatus (with valid values disarmed and armed) and lightStatus (values: unlit / lit), where the respective operators record the current state of the objects they operate. Table 2-8 shows how the subset of attributes related to use case UC-4: Inspect Access History is systematically derived based on the detailed description of UC-4 (Section 2.3.3).
Table 2-8: Attributes for use case UC-4: Inspect Access History. Concept Attributes users Search identity Request search parameters search Postprocessor parameters records list complaint Investigation description Request tracking number current Archiver tracking number contact Notifier information Attribute Description Used to determine the actors credentials, which in turn specify what kind of data this actor is authorized to view. Time frame, actor role, door location, event type (unlock, lock, power failure, etc.). Copied from search request; needed to Filter the retrieved records to match the actors search criteria. List of interesting records selected for further investigation.

Describes the actors suspicions about the selected access records. Allows tracking of the investigation status. Needed to assign a tracking number to complaints and requests. Contact information of the Landlord who accepts complaints and requests for further investigation.

Ivan Marsic

Rutgers University

82

One more attribute that could be considered is for the Page Maker to store the data received from Database Proxy. Recall that earlier we merged the Postprocessor concept with Page Maker, which now also has the responsibility to filter the retrieved records to match the actors search criteria. In Figure 2-10, another possible candidate attribute is numOfKeys in the KeyStorage. However, this is a kind of trivial attribute not worth mentioning, because it is self-evident that the storage should know how many keys it holds inside. An attribute numOfTrials counts the number of failed trials for the user before sounding the alarm bell, to tolerate inadvertent errors when entering the key code. In addition, there should be defined the maxNumOfTrials constant. At issue here is which concept should possess these attributes? Because a correct key is needed to identify the user, the system cannot track a user over time if it does not know users identity (a chicken and egg problem!). One option is to introduce real-world constraints, such as temporal continuity, which can be stated as follows. It is unlikely that a different user would attempt to open the doors within a very short period of time. Thus, all attempts within, say, two minutes can be ascribed to the same user10. For this we need to introduce an additional attribute maxTrialPeriod or, alternatively, we can specify the maximum interval between two consecutive trials, maxInterTrialInterval. The knowledge or expertise required for the attempts-counting worker comprises the knowledge of elapsed time and the validity of the last key typed in within a time window. The responsibilities of this worker are: 1. If numOfTrials numOfTrials = 0
maxNumOfTrials, sound the alarm bell and reset

2. Reset numOfTrials = 0 after a specified amount of time (if the user discontinues the attempts before reaching maxNumOfTrials) 3. Reset numOfTrials = 0 after a valid key is presented A likely candidate concept to contain these attributes is the KeyChecker, because it is the first to know the validity of a presented key. However, it may be argued that instead they should have been inserted into Controller, or a separate worker may need to be introduced only to handle this task. This issue will be further discussed later when we introduce the AlarmCtrl concept. As already said, during the analysis we should make every effort to stay with what needs to be done and avoid considering how things are done. Unfortunately, as seen earlier, this is not always possible. The requirement of tolerating inadvertent typing errors has led us into considerable design detail and, worse, we are now committed to a specific technical solution of the problem.

2.4.3

Contracts: Preconditions and Postconditions

Contracts express any important conditions about the attributes in the domain model. In addition to attributes, contract may include facts about forming or breaking relations between concepts,

10

Of course, this is only an approximation. We could imagine, for instance, the following scenario. An intruder makes numOfTrials = maxNumOfTrials - 1 failed attempts at opening the lock. At this time, a tenant arrives and the intruder sneaks away unnoticed. If the tenant makes a mistake on the first attempt, the alarm will be activated, and the tenant might assume that the system is malfunctioning.

Chapter 2

Object-Oriented Software Engineering

83

and the time-points at which instances of concepts are created or destroyed. You can think of a software contract as equivalent to a rental contract, which spells out the condition of an item prior to renting, and will spell out its condition subsequent to renting. For example, for the operations Unlock and Lock, the possible contracts are: Operation Unlock Preconditions set of valid keys known to the system is not empty numOfTrials < maxNumOfTrials numOfTrials = 0,
Postconditions

for the first trial of the current user if the entered Key Valid keys

numOfTrials = 0,

current instance of the Key object is archived and destroyed The system should be fair, so each user should be allowed the same number of retries (maxNumOfTrials). Thus, the precondition about the system for a new user is that numOfTrials starts at zero value. (I already discussed the issue of detecting a new user and left it open, but let us ignore it for now.) The postcondition for the system is that, after the current user ends the interaction with the system, numOfTrials is reset to zero.
Operation Preconditions Postconditions

Lock None (that is, none worth mentioning) lockStatus = armed, and lightStatus remains unchanged (see text for discussion)

In the postconditions for Lock, we explicitly state that lightStatus remains unchanged because this issue may need further design attention before fully solved. For example, we may want to somehow detect the last person leaving the home and turn off the light behind them. The operation postconditions specify the guarantees of what the system will do, given that the actor fulfilled the preconditions for this operation. The postconditions must specify the outcomes for worst-case vs. average-case vs. best-case scenarios, if such are possible.

2.5 Design: Assigning Responsibilities

A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away. Antoine De Saint-Exupry with proper design, the features come cheaply. This approach is arduous, but continues to succeed. Dennis Ritchie

Ivan Marsic

Rutgers University

84

System Sequence Diagram

Controller

Design Sequence Diagram

: Checker : KeyStorage : LockCtrl

User

: System

ystem

checkKey()
Timer
offstage actor

sk := getNext()

initiating actor select function(unlock") prompt for the key

alt
enter key verify key

val != null

setOpen(true)

signal: valid key, lock open open the lock, turn on the light

[else]

val == null : setLit(true)

start ("duration)

Figure 2-13: Designing object interactions: from system sequence diagrams to interaction diagrams. The magnifier glass symbolizes looking at interactions inside the system.

Resident

:InterfacePage

:SearchRequest

:Controller

:PageMaker

:DatabaseProxy

:Archiver

:Notifier

:InvestigRequest

Database

Landlord

Figure 2-14: The design problem seen as connecting the dots on the map of participating objects.

Analysis dealt with what is needed for our system; we determined how the customer interacts with the system to obtain services and what workers (concepts) need to be acquired to make this possible. Analysis is in a way the acquisition phase of the enterprise establishment. Design, on the other hand, deals with organization, how the elements of the system work and interact. Therefore, design is mainly focused on the dynamics of the system. Unlike analysis, where we deal with abstract concepts, here we deal with concrete software objects. We already encountered system sequence diagrams in Section 2.3.3. As Figure 2-13 illustrates, in the design phase we are zooming-in inside the system and specifying how its software objects interact to produce the behaviors observed by the actors. One way to think about the design problem is illustrated in Figure 2-14. Imagine that you draw a map showing the actors and objects as stations to be visited in the course of executing a use case scenario. The goal of design is to connect the dots/stations in a way that is in some sense optimal. Initially, we know that the

Chapter 2

Object-Oriented Software Engineering

85

: DatabaseProxy

: PageMaker

: Controller

: Checker

: LockCtrl

accessList := retrieve(params : string)

checkKey()

R1.
interfacePage := render(accessList : string)

? (b)

setOpen(true)

R2.

(a)

Figure 2-15: Example of assigning responsibilities. (a) Which objects should be assigned responsibilities R1 and R2? (b) Once the Checker decides the key is valid, the LockCtrl should be notified to unlock the lock. Whose responsibility should this be?

path starts with the initiating actor, because the purpose of the system is to assist the initiating actor to achieve his or her goal. The path also ends with the initiating actor after the system returns the computation results. In between, the path should visit the participating actors. So, we know the entry and exit point(s), and we know computing responsibilities for concepts, as derived in domain analysis (Section 2.4). Objects need to be called (by sending messages) to fulfill their computing (doing) responsibility, and we need to decide how to connect the dots. That is, we need is to assign messaging responsibilities. We need to decide who calls each worker object and for thing objects, we need to decide who creates them, who uses them, and who updates them. Software designers key activity is assigning responsibilities to the software objects acquired in domain analysis (Section 2.4). Consider, for example, use case UC-4: Inspect Access History for which the doing (D) and knowing (K) responsibilities are given in Table 2-6 (Section 2.4.1). Suppose that we want to design the interactions only for Steps 4 6 of use case UC-4. Start at the point when the system receives the search criteria from the actor and stop at the point when an HTML page is prepared and sent to actors browser for viewing. Dynamic object interactions are represented using UML sequence diagrams. Figure 2-15(a) shows the dilemma of responsibility assignment for the example of use case UC-4. First, we notice that among the objects in Table 2-6 Archiver, Notifier, and Investigation Request do not participate in Steps 4 6 of UC-4. Hence, we need to consider only Database Proxy and Page Maker. (Controller participates in every interaction with the initiating actor.) Second, because this is a Web-based solution, the design will need to be adjusted for the Web context. For example, Interface Page will not be a class, but an HTML document (with no class specified). The Search Request will be sent from the browser to the server as plain text embedded in an HTTP message. List of the responsibilities to be assigned (illustrated in Figure 2-15(a)): R1. Call Database Proxy (to fulfill Rs5, defined in Table 2-6 as: retrieve the records from the database that match the search criteria) R2. Call Page Maker (to fulfill Rs3, defined in Table 2-6 as: render the retrieved records into an HTML document)

Ivan Marsic

Rutgers University

86

There is also the responsibility (R3) to check if the list of records retrieved from the database is empty (because there are no records that match the given search criteria). Based on the outcome, a different page will be shown to the actor.
INTERACTION DIAGRAMS

Interaction diagrams display protocolspermitted dynamic relations among objects in the

course of a given activity. Here I highlight the main points and the reader should check the details in a UML reference. You read a UML sequence diagram from the top down: At the top, each box represents an object, which may be named or not. If an object is named, the name is shown in the box to the left of the colon. The class to which the object belongs is shown to the right of the colon. Each timeline (dashed vertical line) describes the world from the vantage point of the object depicted at the top of the timeline. As a convention, time proceeds downward, although in a concurrent program the activities at the same level do not necessarily occur at the same time (see Section 5.3). Thin elongated boxes on a timeline represent the activities of the particular object (the boxes/bars are optional and can be omitted) Links (solid horizontal lines with arrows) between the timelines indicate the followedby relation (not necessarily the immediately-followed-by relation). The link is annotated with a message being sent from one object to another or to itself. Normally, all messages are method calls and, as such, must return. This is denoted by a dashed horizontal link at the bottom of an activity box, oriented opposite of the message arrow. Although this link is often omitted if the method has no return value, the call returns nonetheless. I have noticed that some novices just keep drawing message arrows in one direction and forget that these must return at some point.

Another example is shown in Figure 2-15(a) for use case UC-1: Unlock. Here the dilemma is, who should invoke the method setDisarmed() on the LockCtrl once the key validity is established? One option is the Checker because it is the first to acquire the information about the key validity. Another option is the Controller, because Controller would need to know this information anywayto signal to the user the outcome of the key validity checking. The advantage of the latter option would be to maintain the Checker focused on its specialty and avoid assigning too many responsibilities to it. Before I present solutions to problems in Figure 2-15, I will first describe some criteria that could guide our design decisions. Our goal is to come up with a good design or, ideally, an optimal design. Unfortunately, at present software engineering discipline is unable to precisely specify the quantitative criteria for evaluating designs. Some criteria are commonly accepted, but there is no systematic framework. For example, good software designs are characterized with Short communication chains between the objects Balanced workload across the objects Low degree of connectivity (associations) among the objects

Chapter 2

Object-Oriented Software Engineering

87

While optimizing these parameters we must ensure that messages are sent in the correct order and other important constraints are satisfied. As already stated, there are no automated methods for software design; software engineers rely on design heuristics. The design heuristics used to achieve optimal designs can be roughly divided as: 1. Bottom-up (inductive) approaches that are applying design principles and design patterns locally at the level of objects. Design principles are described in the next section and design patterns are presented in Chapter 5. 2. Top-down (deductive) approaches that are applying architectural styles globally, at the system level, in partitioning the system into subsystems. Software architectures are reviewed in Section 2.6. Software engineer normally combines both approaches opportunistically. While doing design optimization, it is also important to enforce the design constraints. Object constraint specification is reviewed in Section 3.2.3.

2.5.1

Design Principles for Assigning Responsibilities

This design approach is a micro-level design that works at the local level of software objects. It is also known as responsibility-driven design (RDD). Let us reiterate the types of responsibilities that objects can have (Section 1.4): Type 1: Memorizing data or references, such as data values, data collections, or references to other objects, represented as a property Type 2: Performing computations, such as data processing, control of physical devices, etc., represented as a method Type 3: Communicating with other objects, represented as message (method invocation)

Hence, we need to decide what properties and methods belong to what object and what messages are sent by objects. We have already performed responsibility assigning in the analysis phase (Section 2.4). There, we hired workers to perform certain tasks, which in effect covers the first two types of responsibility: assigning attributes, associations, and methods for performing computations. At this stage we are dealing mainly with the third responsibility type: sending messages to (invoking methods on) other objects. Important design principles at the local, objects level include:
Expert Doer Principle: that who knows should do the task High Cohesion Principle: do not take on too many responsibilities of Type 2 (computation) Low Coupling Principle: do not take on too many responsibilities of Type 3 (communication)

Expert Doer Principle helps shorten the communication chains between the objects. It essentially states that, when considering a message sending assignment, the object to send the message should be the one which first gets hold of information needed to send the message. High Cohesion Principle helps in balancing the workload across the objects and keeping them focused.

Ivan Marsic

Rutgers University

88

Objects functional cohesion is inversely proportional to the number of computing responsibilities assigned to it. Low Coupling Principle helps to reduce the number of associations among the objects. Objects coupling is directly proportional to the number of different messages the object sends to other objects. Let us consider how these design principles could be employed in the example of Figure 2-15(b). For example, because the Checker is the first to acquire the information about the key validity, by the Expert Doer Principle it could considered as a good candidate to send a message to the LockCtrl to disarm the lock. However, the High Cohesion Principle prefers maintaining the Checker functionally focused on its specialty and avoid assigning too many responsibilities to it. Suppose we let High Cohesion override Expert Doer. Then, the responsibility to notify the LockCtrl will be assigned to the Controller. It should be noticed that this solution also works against the Low Coupling Principle, because Controller acquires relatively large number of associations. Obviously, the above design principles do not always work hand-in-hand with each other. Often, the designer is faced with conflicting demands and must use judgment and experience to settle for a compromise solution that he or she feels is optimal in the current context. It is important to document the alternative solutions that were considered in the design process, identify all the tradeoffs encountered and explain why the alternatives were abandoned. Table 2-9 lists the communication (message sending / method invocation) responsibilities for the system function enter key (refer to the system sequence diagram in Figure 2-7). Some responsibilities are obvious, such as invoking KeyChecker to validate the key entered by the user, and are not shown.
Table 2-9: Communicating responsibilities identified for the system function enter key. Responsibility Description Send message to LockCtrl to disarm the lock device. Send message to LightCtrl to switch the light bulb on. Send message to PhotoObserver to report whether daylight is sensed. Send message to AlarmCtrl to sound the alarm bell.

Example of Assigning Responsibilities

Let us go back to the problem of assigning responsibilities for UC-1 and UC-4 of the safe home access case study, presented in Figure 2-15. We first consider use case UC-4: Inspect Access History, and design the interactions only for Steps 4 6. We first identify and describe alternative options for assigning responsibilities identified above with Figure 2-15(a). Assigning responsibility R1 for calling Database Proxy is relatively straightforward. The object making the call must know the search parameters; this information is first given to the Controller, so by Expert Doer design principle, Controller should be assigned responsibility R1. As for R2, there are alternative options. The object making the call must know the access list as retrieved from the Database. The feasible alternatives are: 1. Database Proxy is the first to get hold of the access list records

Chapter 2

Object-Oriented Software Engineering

89

Resident

html interfacePage :

: Controller

: PageMaker

: DatabaseProxy

Database

specify search request

get(searchRequest : string) accessList := retrieve(params : string) retrieve records result interfacePage := render(accessList : string) alt accessList != NULL page := renderList() [else] page := warning()

result displayed

post page

Figure 2-16: Sequence diagram for part of use case UC-4: View Access History.

2. Controller will probably be posting the Interface Page rendered by Page Maker, so it would be convenient if Controller receives directly the return value from Page Maker Finally, responsibility R3 to check if the list of records is empty could be assigned to: 1. The object that will be assigned responsibility R2, which can call different methods on Page Maker 2. Page Maker, which will simply generate a different page for different list contents. Next, let us employ the design principles, such as Expert Doer, High Cohesion, or Low Coupling to decide on which object should be given which responsibility. Consider first assigning responsibility R2. By the Expert Doer design principle, Database Proxy should make the call. However, this option lowers the cohesion of Database Proxy because now it would know who is the next in the chain to process the retrieved list, plus it also would need to know what to do with the rendered page that will be returned from Page Maker. If we assign R2 to Database Proxy then Database Proxy should probably return the rendered page that it obtains from Page Maker, rather than the retrieved list (as shown in Figure 2-15(a)). In other words, the method signature should be modified. Conversely, Controller generally has the responsibility to delegate tasks, so the High Cohesion design principle argues for assigning R2 to Controller. Both options (Database Proxy vs. Controller) contribute the same amount of coupling. Therefore, we have a conflict between the design principles: Expert Doer argues for assigning R2 to Database Proxy while High Cohesion argues for assigning R2 to Controller). In this case, one may argue that maintaining high cohesion is more advantageous than satisfying Expert Doer. Database Proxy already has a relatively complex responsibility and adding new responsibilities will only make things worse. Therefore, we opt for assigning R2 to Controller. Responsibility R3 should be assigned to Page Maker because this results in the highest degree of cohesion. Figure 2-16 shows the corresponding UML sequence diagram.

Ivan Marsic

Rutgers University

90

: Controller enterKey()

k : Key

: Checker

: KeyStorage

: LockCtrl

: PhotoObsrv

: LightCtrl

: AlarmCtrl

: Logger

k := create() val := checkKey(k) loop [for all stored keys] sk := getNext() compare()

logTransaction(k, val) destroy alt val == true setOpen(true) dl := isDaylight()

opt

dl == false

setLit(true)

[else] prompt: "try again" opt

numOfTrials++

numOfTrials == maxNumOfTrials

soundAlarm()

Figure 2-17: Sequence diagram for the system function enter key. Several UML interaction frames are shown, such as loop, alt (alternative fragments, of which only the one with a condition true will execute), and opt (optional, the fragment executes if the condition is true).

Now we consider use case UC-1: Unlock. Based on the responsibility list given in Table 2-9, Figure 2-17 shows an example design for the system function enter key. The Controller object orchestrates all the business logic related with this system function. The rationale for this choice was discussed above in relation to Figure 2-15(b). We also have Logger to maintain the history log of access attempts. Notice that the KeyChecker is named Checker only to save space in the diagram. It is of note that there is a business rule hidden in our design:
IF key ValidKeys THEN disarm lock and turn lights on ELSE increment failed-attempts-counter IF failed-attempts-counter equals maximum number allowed THEN raise alarm

By implementing this rule, the object possesses the knowledge of conditions under which a method can or cannot be invoked. Hence, the question is which object is responsible to know this rule? The needs-to-know responsibility has implications for the future upgrades of modifications.

Chapter 2

Object-Oriented Software Engineering

91

: Controller enterKey()

k : Key

: Checker

: KeyStorage

: LockCtrl

: PhotoObsrv

: LightCtrl

: AlarmCtrl

: Logger

k := create() val := checkKey(k) loop [for all stored keys] sk := getNext() compare()

: LightCtrl

: PhotoSObs

controlLight()
logTransaction(k, val)

dl := isDaylight()

alt

val == true

setOpen(true) dl := isDaylight()

opt

dl == false setLit(true)

a
: Controller k: k := create() checkKey(k)

opt

dl == false

setLit(true)

Key [else] prompt: "try again"

opt

: Checker

numOfTrials++

: KeyStorage

: LockCtrl
soundAlarm()

numOfTrials == maxNumOfTrials

loop sk := getNext()

: LightCtrl

: PhotoSObs

setValid(ok) checkIfDaylightAndIfNotThenSetLit() controlLock(k) ok := isValid() opt ok == true setOpen(true) The caller could be Controller or Checker opt dl == false setLit(true) dl := isDaylight()

Figure 2-18: Variations on the design for the use case Unlock, shown in Figure 2-17.

Changes in the business rules require changes in the code of the corresponding objects. More on anticipating change in Chapter 5. Apparently, we have built an undue complexity into the Controller while striving to preserve high degree of specialization for all other objects. This implies low cohesion in the design; poor cohesion is equivalent to low degree of specialization of (some) objects. The reader should by no means get impression that the design in Figure 2-17 is the only one possible. Some variations are shown in Figure 2-18. For example, in variation (a) the Checker sets the key validity as a flag in the Key object, rather than reporting it as the method call return value. The Key is now passed around and LockCtrl, LightCtrl, and others can check for themselves the validity flag and decide what to do. The result: business logic is moved from the Controller into the objects that operate the devices. Personally, I feel uneasy with this solution where the correct functioning of the system depends on a flag in the Key object. A more elegant solution is presented in Section 5.1. Although the variation in Figure 2-18(b) is exaggerated, I have seen similar designs. It not only assigns an awkward method name, checkIfDaylightAndIfNotThenSetLit(), but worse, it imparts the knowledge encoded in the name onto the caller. Anyone examining this diagram can infer that the caller rigidly controls the callees work. The caller is tightly coupled to the callee because it knows the business logic of the callee. A better solution is in Figure 2-18(c). Note that the system GUI design is missing, but that is OK because the GUI can be designed independently of the systems business logic.

Ivan Marsic

Rutgers University

92

KeyChecker + checkKey(k : Key) : boolean 1 checker

Key code_ : string timestamp_ : long doorLocation_ : string

1..*

KeyStorage + getNext() : Key validKeys 1

Controller # numOfTrials_ : long # maxNumOfTrials_ : long + enterKey(k : Key) 1

PhotoSObsrv

LightCtrl # lit_ : boolean + isLit() : boolean + setLit(v : boolean) 1 lightCtrl

sensor + isDaylight() : boolean

lockCtrl 1 logger

1 1 alarmCtrl

LockCtrl # open_ : boolean + isOpen() : boolean + setOpen(v : boolean)

Logger + logTransaction(k : Key)

AlarmCtrl + soundAlarm()

Figure 2-19: Class diagram for the home access system under development.

2.5.2

Class Diagram

Class diagram is created by simply reading it off of the interaction diagrams. The class diagram of our system is shown in Figure 2-19. Notice the differences and similarities with the domain model, Figure 2-10. Because class diagram gathers class operations and attributes in one place, it is easier to size up the relative complexity of classes in the system. The number of operations in a class correlates with the amount of responsibility handled by the class. Good OO designs distribute expertise and workload among many cooperating objects. If you notice that some classes have considerably greater number of operations than others, you should examine the possibility that there may be undiscovered class(es) or misplaced responsibilities. Look carefully at operation names and ask yourself questions such as: Is this something I would expect this class to do? Or, Is there a less obvious class that has not been defined?

Class Relationships
Class diagram both describes classes and shows the relationships among them. I already discussed object relationships in Section 1.4.1. Generally, the following types of relationships are possible: Is-a relationship (hollow triangle symbol ): A class is a kind of another class Has-a relationship: A class contains another class Composition relationship (filled diamond symbol ): The contained item is a integral part of the containing item, such as a leg in a desk Aggregation relationship (hollow diamond symbol ): The contained item is an element of a collection but it can also exist on its own, such as a desk in an office

Chapter 2

Object-Oriented Software Engineering

93

S11 S

A A

B B

A A

B B

P P

S22 S

(a)

(b)

SN SN

(c)

Figure 2-20: Example object communication patterns. (a) One-to-one direct messages. (b) One-to-many untargeted messages. (c) Via a shared data element.

Uses-a relationship (arrow symbol ): A class uses another class Creates relationship: A class creates another class

In our particular case, Figure 2-19, there is an aggregation relationship between KeyStorage and Key; all other relationships happen to be of the uses type. The reader should also notice the visibility markers for class attributes and operations: + for public, global visibility; # for protected visibility within the class and its descendant classes; and, for private within-the-classonly visibility. Class diagram is static, unlike interaction diagrams, which are dynamic.

Generic Object Roles

As a result of having specific responsibilities, the members of object community usually develop some stereotype roles. Structurer Bridge

Note that objects almost never play an exclusive role; several roles are usually imparted to different degree in each object.

Object Communication Patterns

Communication pattern is a message-sending relation imposed on a set of objects. As with any relation, it can be one-to-one or one-to-many and it can be deterministic or random. Some of these are illustrated in Figure 2-20. Object-oriented design, particularly design patterns, is further elaborated in Chapter 5.

Ivan Marsic

Rutgers University

94

User Interaction

User Authentication

Archiving

Management of Sensors and Devices

Communication w. Police Station

User Interface Layer

Domain Layer (Application Logic)

Technical Services Layer

Figure 2-21: Software packages for the case study system. The system has a layered architecture, with three layers indicated.

2.5.3

Why Software Engineering Is Difficult (2)

Another key cause is the lack of analytical methods for software design. Software engineers are aiming at optimal designs, but quantitative criteria for optimal software design are largely unknown. Optimality criteria appear to be mainly based upon judgment and experience.

2.6 Software Architecture

Bottom-up design approaches at the local level of objects, reviewed in the previous section, are insufficient to achieve optimal designs, particularly for large systems. A complementary approach are system-level (macro-level), global design approaches which help us to see the forest for the trees. These approaches partition the system into logical units or follow some global organizational patterns. Objects through their relationships form confederations, which are composed of potentially many objects and often have a complex behavior. The synergy of the cooperative efforts among the members creates a new, higher-level conceptual entity. Organizations are partitioned in departmentsdesign, manufacturing, human resources, marketing, etc. Of course, partitioning makes sense for certain size of the organization; partitioning a small organization in departments and divisions does not make much sense. Similarly, our virtual organization of objects should be partitioned into software packages. Each package contains a set of logically related classes.

System architects may partition an application into subsystems early in design. But subsystems can be discovered later, as the complexity of the system unfolds.

Chapter 2

Object-Oriented Software Engineering

95

Flow Control
An important feature of most programming languages is the conditional. This is a statement that causes another statement to execute only if a particular condition is true. One can use simple sentences to advise the machine, Do these fifteen things one after the other; if by then you still havent achieved such-and-such, start all over again at Step 5. Equally, one can readily symbolize a complex conditional command such as: If at that particular point of runtime, this happens, then do so-and-so; but if that happens, then do such-and-such; if anything else happens, whatever it is, then do thus-and-so. Note that in the case of IF-THEN-ELSE, the occasion for action is precisely specified. One can also set up daemons that spend their lifetime on the lookout for a certain type of event, and do what they have to do whenever a happening of that type occurs. A more flexible IF-THEN-ELSE is to say, If this happens, use that method to choose an appropriate procedure from this list of procedures, where the contents of the list in question can vary as the program runs. IF-THEN-ELSE partitions the set of all possible situations in two or more cases. The partition may turn out to be too rigid, there may be some exception cases that were not anticipated and now need to be accounted for. Possibly even by the user! A key issue is, How to let the user to rewire the paths/flows within the program if a need arises?

2.7 Implementation and Testing

The good news about computers is that they do what you tell them to do. The bad news is that they do what you tell them to do. Ted Nelson Real programmers dont comment their code. If it was hard to write, it should be hard to understand. Unknown

This section shows how the designed system might be implemented. (The reader may wish to review the Java programming refresher in Appendix A before proceeding.) One thing that programmers often neglect is that the code must be elegant and readable. This is not for the sake of the computer which will run the code, but for the sake of humans who will read, maintain, and improve on the original code. I believe that writing good comments is at least as difficult as writing good code. It may be even more important, because comments describe the developers intention, while the code expresses only what the developer did. The code that lacks aesthetics and features poor writing style in comments is likely to be a poor quality code.11

11

On a related note, writing user messages is as important. The reader may find that the following funny story is applicable to software products way beyond Microsofts: There was once a young man who wanted to become a great writer and to write stuff that millions of people would read and react to on an emotional level, cry, howl in pain and anger, so now he works for Microsoft, writing error messages. [ Source: A Prairie Home Companion, February 3, 2007. Online at: http://prairiehome.publicradio.org/programs/2007/02/03/scripts/showjokes.shtml ]

Ivan Marsic

Rutgers University

96

Light bulb RS-232 Interface cable Switch Photosensor Computer Keypad and Embedded processor

Alarm bell

Figure 2-22: Hardware components for the system implementation.

Assume we have an embedded processor with a keypad, wired to other hardware components of the system, as shown in Figure 2-22. The embedded processor accepts commands from the computer via a RS-232 serial port and simply passes them on the corresponding device. The many intricacies of serial communication are omitted and the interested reader is directed to the bibliography review at the end of this chapter. The embedded processor may in an advanced design become a full-featured computer, communicating with the main computer via a local area network (LAN). The following code uses threads for concurrent program execution. The reader not familiar with threads should consult Section 5.3. The key purpose of the main class is to get hold of the external information: the table of valid keys and a connection to the embedded processor that controls the devices. Following is an implementation for the main system class.

Listing 2-1: Implementation Java code of the main HomeAccessControlSystem, of the case-study home-access system.
import import import import javax.comm.*; java.io.IOException; java.io.InputStream; java.util.TooManyListenersException;

class,

called

public class HomeAccessControlSystem extends Thread implements SerialPortEventListener { protected Controller contrl_; // entry point to the domain logic protected InputStream inputStream_; // from the serial port protected StringBuffer key_ = new StringBuffer(); // user key code public static final long keyCodeLen_ = 4; // key code of 4 chars public HomeAccessControlSystem( KeyStorage ks, SerialPort ctrlPort ) { try { inputStream_ = ctrlPort.getInputStream(); } catch (IOException e) { e.printStackTrace(); }

Chapter 2

Object-Oriented Software Engineering

97

LockCtrl lkc = new LockCtrl(ctrlPort); LightCtrl lic = new LightCtrl(ctrlPort); PhotoObsrv sns = new PhotoObsrv(ctrlPort); AlarmCtrl ac = new AlarmCtrl(ctrlPort); contrl_ = new Controller(new KeyChecker(ks), lkc, lic, sns, ac); try { ctrlPort.addEventListener(this); } catch (TooManyListenersException e) { e.printStackTrace(); // limited to one listener per port } start(); // start the thread } /** The first argument is the handle (filename, IP address, ...) * of the database of valid keys. * The second arg is optional and, if present, names * the serial port. */ public static void main(String[] args) { KeyStorage ks = new KeyStorage(args[1]); SerialPort ctrlPort; String portName = "COM1"; if (args.length > 1) portName = args[1]; try { CommPortIdentifier cpi = CommPortIdentifier.getPortIdentifier(portName); if (cpi.getPortType() == CommPortIdentifier.PORT_SERIAL) { ctrlPort = (SerialPort) cpi.open(); new HomeAccessControlSystem(ks, ctrlPort); } catch (NoSuchPortException e) { System.err.println("Usage: ... ... port_name"); } try { ctrlPort.setSerialPortParams( 9600, SerialPort.DATABITS_8, SerialPort.STOPBITS_1, SerialPort.PARITY_NONE ); } catch (UnsupportedCommOperationException e) { e.printStackTrace(); } } /** Thread method; does nothing, just waits to be interrupted * by input from the serial port. */ public void run() { while (true) { try { Thread.sleep(100); } catch (InterruptedException e) { /* do nothing */ } } } /** Serial port event handler

Ivan Marsic

Rutgers University

98

* Assume that the characters are sent one by one, as typed in. */ public void serialEvent(SerialPortEvent evt) { if (evt.getEventType() == SerialPortEvent.DATA_AVAILABLE) { byte[] readBuffer = new byte[5]; // just in case, 5 chars try { while (inputStream_.available() > 0) { int numBytes = inputStream_.read(readBuffer); // could check if "numBytes" == 1 ... } } catch (IOException e) { e.printStackTrace(); } // append the new char to the user key key_.append(new String(readBuffer)); if (key_.length() >= keyCodeLen_) { // got whole key? // pass on to the Controller contrl_.enterKey(key_.toString()); // get a fresh buffer for a new user key key_ = new StringBuffer(); } } } }

The class HomeAccessControlSystem is a thread that runs forever and accepts the input from the serial port. This is necessary to keep the program alive, because the main thread just sets up everything and then terminates, while the new thread continues to live. Threads are described in Section 5.3. Next shown is an example implementation of the core system, as designed in Figure 2-17. The coding of the system is directly driven by the interaction diagrams.

Listing 2-2: Implementation Java code of the classes Controller, KeyChecker, and LockCtrl.
import javax.comm.*; public class Controller { protected KeyChecker checker_; protected LockCtrl lockCtrl_; protected LightCtrl lightCtrl_; protected PhotoObsrv sensor_; protected AlarmCtrl alarmCtrl_; public static final long maxNumOfTrials_ = 3; public static final long trialPeriod_ = 600000; // msec [= 10 min] protected long numOfTrials_ = 0; public Controller( KeyChecker kc, LockCtrl lkc, LightCtrl lic, PhotoObsrv sns, AlarmCtrl ac ) { checker_ = kc; lockCtrl_ = lkc; alarmCtrl_ = ac; lightCtrl_ = lic; sensor_ = sns;

Chapter 2

Object-Oriented Software Engineering

99

} public enterKey(String key_code) { Key user_key = new Key(key_code) if (checker_.checkKey(user_key)) { lockCtrl_.setArmed(false); if (!sensor_.isDaylight()) { lightCtrl_.setLit(true); } numOfTrials_ = 0; } else { // we need to check the trial period as well, but ... if (++numOfTrials_ >= maxNumOfTrials_) { alarmCtrl_.soundAlarm(); numOfTrials_ = 0; // reset for the next user } } } } import java.util.Iterator; public class KeyChecker { protected KeyStorage validKeys_; public KeyChecker(KeyStorage ks) { validKeys_ = ks; } public boolean checkKey(Key user_key) { for (Iterator e = validKeys_.iterator(); e.hasNext(); ) { if (compare((Key)e.next(), user_key) { return true; } } return false; } protected boolean compare(Key key1, Key key2) { } } import javax.comm.*; public class LockCtrl { protected boolean armed_ = true; public LockCtrl(SerialPort ctrlPort) { } }

In Listing 2-2 I assume that KeyStorage is implemented as a list, java.util.ArrayList. If the keys are simple objects, e.g., numbers, then another option is to use a hash table, java.util.HashMap. Given a key, KeyStorage returns a value of a valid key. If the return value is null, the key is invalid. The keys must be stored in a persistent storage, such as relational database or a plain file and loaded into the KeyStorage at the system startup time, which is not shown in Listing 2-2.

Ivan Marsic

Rutgers University

100

The reader who followed carefully the stepwise progression from the requirements from the code may notice that, regardless of the programming language, the code contains many details that usually obscure the high-level design choices and abstractions. Due to the need for being precise about every detail and unavoidable language-specific idiosyncrasies, it is difficult to understand and reason about software structure from code only. I hope that at this point the reader appreciates the usefulness of stepwise progression and diagrammatic representations.

2.7.1

Software Testing

Testing is often taken to mean executing a program to see whether it produces the correct output for a given input. This implies testing the end-product, the software itself, which in turn means that testing activities are postponed until late in the lifecycle. This is wrong because experience has shown that errors introduced during the early stages are the costliest and most difficult to discover. A more general definition is that testing is the process of finding faults in software artifacts. A fault, also called defect or bug, is an erroneous hardware or software element of a system that can cause the system to fail, i.e., to behave in a way that is not desired or even harmful. We say that the system experienced failure because of a built-in fault. Any software artifact can be tested, including requirements specification, design, and design specification. Testing activities should be started as early as possible. An extreme form of this approach is test-driven development (TDD), one of the practices of Extreme Programming (XP), in which development starts with writing tests. The form and rigor of testing should be adapted to the nature of the artifact that is being tested. Testing design sketches will be approached differently than testing a software code. Testing software artifacts shows only the presence of errors, not their absence. This means exhaustively trying all possible combinations of inputs and following all possible paths through the program. This may not be practically achievable for large software, because the number of possible combinations grows exponentially with software size. An alternative to this brute force approach to testing is to prove the correctness of the software. Unfortunately, proving correctness generally cannot be automated and requires human effort. In addition, it can be applied only in the projects where the requirements are specified in a formal (mathematical) language. We will discuss this issue further in Chapter 3. Testing is usually guided by the hierarchical structure of the system as designed during the analysis and design phases. Rather than testing the system as a whole, we start by testing individual components, which is known as unit testing. These components are incrementally integrated into a system. Testing the composition of components is known as integration testing. Executing tests on single components or composition of components requires that the tested thing be isolated from the rest of the system. Test drivers and test stubs are used to substitute for missing parts of the system. A test driver simulates the part of the system that invokes operations on the tested component. A test stub simulates the components that are called by the tested component. The thing to be tested is also known as the fixture. Each testing method follows this cycle: 1. Create the thing to be tested (fixture), the test driver, and the test stub(s) 2. Have the test driver invoke an operation on the fixture

Chapter 2

Object-Oriented Software Engineering

101

Test driver

Tested component

Test stubs

: Controller enterKey()

k : Key

: Checker

: KeyStorage

testDriver : start()

: Checker

k : Key

: KeyStorage

k := create() val := checkKey(k) loop [for all stored keys] sk := getNext() compare()

k := create() result := checkKey(k) loop [for all stored keys] sk := getNext() compare()

display result

(a)

(b)

Figure 2-23: Testing the Key Checkers operation checkKey() (use case Unlock). (a) Part of the sequence diagram excerpted from Figure 2-17. (b) Test stubs and drivers for testing the Key Checker.

3. Evaluate that the results are as expected Suppose you want to test the Key Checker class of the safe-home-access case study that we designed in Section 2.5 and implemented in Listing 2-2. Figure 2-23(a) shows an excerpt sequence diagram extracted from Figure 2-17. Class Checker is the tested component and we need to implement a test driver to substitute Controller and test stubs to substitute KeyStorage and Key classes. As shown in Figure 2-23(b), the test driver passes the test inputs to the tested component and displays the results. It can be any object type, not necessarily an instance of the Controller class. Unlike this, the test stubs must be of the same class as the components they are simulating. They must provide the same operation APIs, with the same return value types. The implementation of test stubs is a nontrivial task and, therefore, there is a tradeoff between implementing accurate test stubs and using the actual components. That is, if KeyStorage and Key class implementations are available, we could use them when testing the Key Checker class.

Unit Testing
Unit testing finds differences between the object design model and its corresponding implementation. There are several benefits of focusing on individual components. One is the common advantage of the divide-and-conquer approachit reduces the complexity of the problem and allows us to deal with smaller parts of the system separately. Second, unit testing makes it easier to locate and correct faults because only few components are involved in the process. Lastly, unit testing supports division of labor, so several team members can test different components in parallel with one another. There exist many unit testing techniques. Some of the most popular include: equivalence testing, boundary testing, path testing, and state-based testing.

Ivan Marsic

Rutgers University

102

Equivalence Testing

Equivalence testing is a black-box testing method that divides the domain of input parameters for a component into similarity-based classes of data. The idea is to reduce the total number of test cases by selecting representative input values from each equivalence class. The assumption is that the system will behave similarly for all inputs from an equivalence class. Equivalence testing has two steps: (i) partitioning the values of input parameters into equivalence classes and (ii) choosing the test input values. Partitioning the values of input parameters into equivalence classes may be performed according to the following guidelines: For an input parameter specified over a range of values, partition the value space into one valid and two invalid equivalence classes. For example, if the allowed values are integers between 0 and 100, the valid equivalence class contains integers between 0 and 100, one invalid equivalence class contains all negative integers, and the other invalid equivalence class contains all integers greater than 100. For an input parameter specified with a particular value, partition the value space into one valid and two invalid equivalence classes. For example, if the allowed value is a real number 1.4142, the valid equivalence class contains a single element {1.4142}, one invalid equivalence class contains all real number smaller than 1.4142, and the other invalid equivalence class contains all real number greater than 1.4142. For an input parameter specified with a set of values, partition the value space into one valid and one invalid equivalence class. For example, if the allowed value is any element of the set {1, 2, 4, 8, 16}, the valid equivalence class contains the elements {1, 2, 4, 8, 16}, and the invalid equivalence class contains all other elements. For an input parameter specified as a Boolean value, partition the value space into one valid and one invalid equivalence class (one for TRUE and the other for FALSE).

Equivalence classes defined for an input parameter must satisfy the following criteria: 1. Coverage: Every possible input value belongs to an equivalence class. 2. Disjointedness: No input value belongs to more than one equivalence class. 3. Representation: If an operation is invoked with one element of an equivalence class as an input parameter and returns a particular result, then it must return the same result if any other element of the class is used as input. If an operation has more than one input parameter, we must define new equivalence classes for combinations of the input parameters (known as Cartesian product or cross product, see Section 3.2.1). For example, consider testing the Key Checkers operation checkKey(k : Key) (Figure 2-23). As shown in Figure 2-19, class Key has three string attributes: code, timestamp, and doorLocation. The operation checkKey() does not use timestamp, so its value is irrelevant (although in the interest of exhaustive testing we may wish trying it with different values of timestamp!). The other two attributes, code and doorLocation, are specified with a set of values for each. Suppose that the system is installed in an apartment building with apartments numbered as {196, 198, 200, 202, 204, 206, 208, 210}. Assume that the attribute

Chapter 2

Object-Oriented Software Engineering

103

doorLocation takes the value of the associated apartment number. On the other hand, the tenants may have chosen their four-digit access codes as {9415, 7717, 8290, , 4592}. Although a code value 9415 and doorLocation value 198 are each valid separately, their combination is invalid, because the code value for the tenant in apartment 198 is 7717.

Therefore, we must create a cross product of code and doorLocation values and partition this value space into one valid and one invalid equivalence class. For the pairs of test input values chosen from the valid equivalence class, the operation checkKey() should return the Boolean value TRUE. Conversely, for the pairs of test input values from the invalid equivalence class it should return FALSE.
Boundary Testing

Boundary testing is a special case of equivalence testing that focuses on the boundary values of input parameters. Rather than selecting any element from an equivalence class, boundary testing selects elements from the edges of the equivalence class, or outliers. The assumption behind this kind of testing is that developers often overlook special cases at the boundary of equivalence classes. For example, if an input parameter is specified over a range of values from a to b, then test cases should be designed with values a and b as well as just above and just below a and b.

2.8 Summary and Bibliographical Notes

Good judgment comes from experience, and experience comes from bad judgment. Frederick P. Brooks

This chapter presents incremental and iterative approach to software design and gradually introduces software engineering techniques using a running example, which is designed and then improved (refactored) by remedying the perceived deficiencies. Key phases of the process are summarized in Figure 2-24. (Notice that package diagram, which is a structural description, is not shown for the lack of space.) The reader should not mistake this figure to indicate that software lifecycle progresses unidirectionally as in the waterfall method. This is only the logical order in which activities take place. However, in practice there is significant intertwining and backtracking between the steps. Plus, this represents only a single iteration of a multiphase process. In general, the sequential presentation of the material does not imply how the actual development is carried out: teaching the tool use should not be equated with its actual use. Teaching follows logical ordering and practice demands the ordering that produces best results.

Ivan Marsic

Rutgers University

104

: Communicator

: Checker

: KeyStorage

: LockCtrl

import javax.com import java.io.I import java.io.I import java.util

Behavior

Lock Tenant

User
primary actor

: System

checkKey() sk := getNext()

selectFunction(unlock")

alt

val != null

setOpen(true)

prompt for the key

Unlock
enterKey()

[else] open the lock, turn on the light

val == null : setLit(true)

Landlord
signal: valid key, lock open

addElement()

public class Hom implemen

Use Cases

System Description

System Sequence Diagrams

Interaction Diagrams

protected Co protected In protected St public stati

public HomeA KeyStora ) {

KeyChecker + checkKey() : boolean Communicator obtains Key 1 checker Key # code_ : long + getCode() : long 1..*

try { inpu } catch

Structure

KeyChecker numOfTrials maxNumOfTrials

Figure 2-24: Summary of a single iteration of the software development lifecycle. The activity alternates between elaborating the systems behavior vs. structure. Only selected steps and artifacts are shown.

A general understanding of the problem domain is inadequate for success; you need a very detailed understanding of what is expected from the system. A detailed understanding is best developed incrementally and iteratively. Key points: Object orientation allows creation of software in solution objects which are directly correlated to the objects (physical objects or abstract concepts) in the problem to be solved. The key advantage of the object-oriented approach is in the localization of responsibilitiesif the system does not work as intended, it is easier to pinpoint the culprit in an object-oriented system. The development must progress systematically, so that the artifacts created in the previous phase are always being carried over into the next phase, where they serve as the foundation to build upon. Use case modeling is an accepted and widespread technique to gather and represent the business processes and requirements. Use cases describe the scenarios of how the system under discussion can be used to help the users accomplish their goals. Use cases represent precisely the way the software system interacts with its environment and what information must pass the system boundary in the course of interaction. Use case steps are written in an easy-to-understand structured narrative using the vocabulary of the domain. This is engaging for the end users, who can easily follow and validate the use cases, and the accessibility encourages users to be actively involved in defining the requirements.

conveysRequests

Controller
es rifi ve

# numOfTrials_ : long # maxNumOfTrials_ : long + enterKey(k : Key)

PhotoSObsrv

sensor + isDaylight() : boolean

LockCtrl LightCtr

notifiesKeyValidity

LockOperator lockStatus

lockCtrl

1 1 alarmCtrl

LockCtrl # open_ : boolean + isOpen() : boolean + setOpen(v : boolean)

PhotoObs

AlarmCtrl + soundAlarm()

Domain Model Class Diagram

Implementation Program

Chapter 2

Object-Oriented Software Engineering

105

The analysis models are input to the design process, which produces another set of models describing how the system is structured and how the systems behavior is realized in terms of that structure. The structure is represented as a set of classes (class diagram), and the desired behavior is characterized by patterns of messages flowing between instances of these classes (interaction diagrams). Finally, the classes and methods identified during design are implemented in an objectoriented programming language. This completes a single iteration. After experimenting with the preliminary implementation, the developer iterates back and reexamines the requirements. The process is repeated until a satisfactory solution is developed.

The reader should be aware of the capabilities and limitations of software engineering methods. The techniques presented in this chapter help you to find a solution once you have the problem properly framed, as is the case with example projects in Section 1.5. But, use case analysis will not help you with framing the problem; rather, it is intended to lead you towards a solution once the problem is defined. To define the problem, you should consider ethnography methods or, as an engineer you may prefer Jacksons problem frames [Jackson, 2001], described in the next chapter. A short and informative introduction to UML is provided by [Fowler, 2004]. The fact that I adopt UML is not an endorsement, but merely recognition that many designers presently use it and probably it is the best methodology currently available. The reader should not feel obliged to follow it rigidly, particularly if he/she feels that the concept can be better illustrated or message conveyed by other methods. Section 2.2: Requirements Engineering IEEE Standard 830 was last revised in 1998 [IEEE 1998]. The IEEE recommendations cover such topics as how to organize requirements specifications document, the role of prototyping, and the characteristics of good requirements. A great introduction to user stories is [Cohn, 2004]. It describes how user stories can be used to plan, manage, and test software development projects. It is also a very readable introduction to agile methodology. Section 2.3: Use Cases An excellent source on methodology for writing use cases is [Cockburn, 2001]. System sequence diagrams were introduced by [Coleman et al., 1994; Malan et al., 1996] as part of their Fusion Method. Section 2.4: Domain Model The approach to domain model construction presented in Section 2.4 is different from, e.g., the approach in [Larman, 2005]. Larmans approach can be summarized as making an inventory of the problem domain concepts. Things, terminology, and abstract concepts already in use in the problem domain are catalogued and incorporated in the domain model diagram. A more inclusive and complex model of the business is called Business Object Model (BOM) and it is also part of the Unified Process. Section 2.5: Design

Ivan Marsic

Rutgers University

106

Design with responsibilities (Responsibility-Driven Design): [Wirfs-Brock & McKean, 2003; Larman, 2005] Coupling and cohesion as characteristics of software design quality introduced in [Constantine et al., 1974; Yourdon & Constantine, 1979]. More on coupling and cohesion in Chapter 4. See also: http://c2.com/cgi/wiki?CouplingAndCohesion J. F. Maranzano, S. A. Rozsypal, G. H. Zimmerman, G. W. Warnken, P. E. Wirth, and D. M. Weiss, Architecture reviews: Practice and experience, IEEE Software, vol. 22, no. 2, pp. 34-43, March-April 2005. Design should give correct solution but should also be elegant (or optimal). Product design is usually open-ended because it generally has no unique solution, but some designs are better than others, although all may be correct. Better quality matters because software is a living thingcustomer will come back for more features or modified features because of different user types or growing business. This is usually called maintenance phase of the software lifecycle and experience shows that it represents the dominant costs of a software product over its entire lifecycle. Initial design is just a start for a good product and only a failed product will end with a single release.

Section 2.7: Implementation and Testing [Raskin, 2005] [Malan & Halland, 2004] [Ostrand et al., 2004] Useful information on Java programming is available at: http://www.developer.com/ (Gamelan) and http://www.javaworld.com/ (magazine) For serial port communication in Java, I found useful information here (last visited 18 January 2006):
http://www.lvr.com/serport.htm

http://www.cs.tufts.edu/~jacob/150tui/lecture/01_Handyboard.html http://show.docjava.com:8086/book/cgij/exportToHTML/serialPorts/SimpleRead.java.html Also informative is Wikibooks: Serial Data Communications, at: http://en.wikibooks.org/wiki/Programming:Serial_Data_Communications http://en.wikibooks.org/wiki/Serial_communications_bookshelf

Biometrics: Wired START: Keystroke biometrics: That doesnt even look like my typing, Wired, p. 42, June 2005. Online at: http://www.wired.com/wired/archive/13.06/start.html?pg=9 Researchers snoop on keyboard sounds; Computer eavesdropping yields 96 percent accuracy rate. Doug Tygar, a Berkeley computer science professor and the study's principal investigator http://www.cnn.com/2005/TECH/internet/09/21/keyboard.sniffing.ap/index.html Keystroke Biometric Password; Wednesday, March 28, 2007 2:27 PM/EST

Chapter 2

Object-Oriented Software Engineering

107

BioPassword purchased the rights to keystroke biometric technology held by the Stanford Research Institute. On March 26, 2007, the company announced BioPassword Enterprise Edition 3.0 now with optional knowledge-based authentication factors, integration with Citrix Access Gateway Advanced Edition, OWA (Microsoft Outlook Web Access) and Windows XP embedded thin clients. http://blogs.eweek.com/permit_deny/content001/seen_and_heard/keystroke_biometric_password. html?kc=EWPRDEMNL040407EOAD See also [Chellappa et al., 2006] for a recent review on the state-of-the-art in biometrics. The most popular unite testing framework is the xUnit family (for many languages), available at http://www.junit.org. For Java, the popular version is JUnit, which is integrated into most of the popular IDEs, such as Eclipse (http://www.eclipse.org). The xUnit family, including JUnit, was started by Kent Beck (creator of eXtreme Programming) and Eric Gamma (one of the Gang-ofFour design pattern authors (see Chapter 5 below), and the chief architect of Eclipse. A popular free open source tool to automatically rebuild the application and run all unit tests is CruiseControl (http://cruisecontrol.sourceforge.net).

Problems
Problem 2.1
Consider the following nonfunctional requirements and determine which of them can be verified and which cannot. Explain your answers. (a) The user interface must be user-friendly and easy to use. (b) The number of mouse clicks the user needs to perform when navigating to any window of the systems user interface must be less than 10. (c) The user interface of the new system must be simple enough so that any user can use it with a minimum training. (d) The maximum latency from the moment the user clicks a hyperlink in a web page until the rendering of the new web page starts is 1 second over a broadband connection. (e) In case of failure, the system must be easy to recover and must suffer minimum loss of important data.

Problem 2.2

Problem 2.3
Consider an online auction site, such as eBay.com, with selling, bidding, and buying services. Assume that you are a buyer, you have placed a bid for an item, and you just received a notification that the bidding process is

Ivan Marsic

Rutgers University

108

External Light Motion Detector Electric Eye

Remote Receiver

Manual Opener Switch

Motor
Motion detection perimeter

Remote Transmitter

Figure 2-25: Depiction of the problem domain for Problem 2.5.

closed and you won it. Write a single use case that represents the subsequent process of purchasing the item with a credit card. Assume the business model where the funds are immediately transferred to the sellers account, without waiting for the buyer to confirm the receipt of the goods. Also, only the seller is charged selling fees. Start from the point where you are already logged in the system and consider only what happens during a single sitting at the computer terminal. (Unless otherwise specified, use cases are normally considered only for the activities that span a single sitting.) List also some alternate scenarios.

Problem 2.4
Consider the online auction site described in Problem 2.3. Suppose that by observation you determine that the generic Buyer and Seller roles can be further differentiated into more specialized roles: Occasional Buyer, Frequent Buyer, and Collector Small Seller, Frequent Seller, and Corporate Seller

Identify the use cases for both situations: generic Buyers and Sellers vs. differentiated Buyers and Sellers. Discuss the similarities and differences. Draw the use case diagrams for both situations.

Problem 2.5
You are hired to develop a software system for motion detection and garage door control. The system should turn the garage door lights on automatically when it detects motion within a given perimeter. The garage door opener should be possible to control either by a remote radio transmitter or by a manual button switch. The opener should include the following safety feature. An electric eye sensor, which projects invisible infrared light beams, should be used to detect if someone or something passes under the garage door while it closes. If the beam is obstructed while the door is going down, the door should not closethe system should automatically stop and reverse the door movement. The relevant hardware parts of the system are as follows (see Figure 2-25): motion detector external light bulb

Chapter 2

Object-Oriented Software Engineering

109

initiate

TurnLightOn
AnimateObject iate init

TurnLightOff StealOpenerCode RemoteOpen

initiate initia te

Thief
in

te itia

Figure 2-26: A fragment of a possible use case diagram for Problem 2.6.

motor for moving the garage door electric eye sensor remote control radio transmitter and receiver manual opener button switch Assume that all the hardware components are available and you only need to develop a software system that controls the hardware components. (a) Identify the actors for the system and their goals (b) Derive only the use cases relevant to the system objective and write brief or casual text description of each (c) Draw the use case diagram for the system (d) For the use case that deals with the remote-controlled garage door opening, write a fully dressed description (e) Draw the system sequence diagram(s) for the use case selected in (d) (f) Draw the domain model with concepts, associations, and attributes [Note: derive the domain model using only the information that is available so fardo not elaborate the other use cases] (g) Show the operation contracts for the operations of the use case selected in (d)

Problem 2.6
For the system described in Problem 2.5, consider the following security issue. If the remote control supplied with the garage door opener uses a fixed code, a thief may park near your house and steal your code with a code grabber device. The thief can then duplicate the signal code and open your garage at will. A solution is to use so called rolling security codes instead of a fixed code. Rolling code systems automatically change the code each time you operate your garage door. (a) Given the automatic external light control, triggered by motion detection, and the above security issue with fixed signaling codes, a possible use case diagram is as depicted in Figure 2-26. Are any of the shown use cases legitimate? Explain clearly your answer. (b) For the use case that deals with the remote-controlled garage door closing, write a fully dressed description.

Ivan Marsic

Rutgers University

110

(c) Draw the system sequence diagram(s) for the use case selected in (b). (d) Draw the domain model with concepts, associations, and attributes . [Note: derive the domain model using only the information that is available so fardo not elaborate the other use cases.] (e) Show the operation contracts for the operations of the use case selected in (b).

Problem 2.7
Derive the basic use cases for the restaurant automation system (described at the book website, given in Preface). Draw the use case diagram.

Problem 2.8
Identify the actors and derive the use cases for the vehicular traffic information system (described at the book website, given in Preface). Draw the use case diagram. Also, draw the system sequence diagram for the use case that deals with data collection.

Problem 2.9
You are hired to develop an automatic patient monitoring system for a home-bound patient. The system is required to read out the patients heart rate and blood pressure and compare them against specified safe ranges. In case an abnormality is detected, the system must alert a remote hospital. (Notice that the measurements cannot be taken continuously, because heart rate is measured over a period of time, say 1 minute, and it takes time to inflate the blood-pressure cuff.) The system must also check that the analog devices for measuring the patients vital signs are working correctly and report failures to the hospital. Identify the use cases and draw the use case diagram. Briefly, in one sentence, describe each use case but do not elaborate them.

Problem 2.10
Consider a variation of the home access control system which will do user identification based on face recognition, as described in Section 2.3.2. Write the detailed use case descriptions of use cases UC6: AddUser and UC7: RemoveUser for both cases given in Figure 2-4, that is locally implemented face recognition (Case (a)) and remotely provided face recognition (Case (b)).

Problem 2.11
Consider an automatic bank machine, known as Automatic Teller Machine (ATM), and a customer who wishes to withdraw some cash from his or her banking account. Draw a UML activity diagram to represent this use case.

Chapter 2

Object-Oriented Software Engineering

111

Problem 2.12
Derive the domain model with concepts, associations, and attributes for the virtual mitosis lab (described at the book website, given in Preface). Note: You may wonder how is it that you are asked to construct the domain model without first having the use cases derived. The reason is, because the use cases for the mitosis lab are very simple, this is left as an exercise for the reader.

Problem 2.13
Explain the relationship between use cases and domain model objects and illustrate by example.

Problem 2.14
An example use case for the system presented in Section 1.5.1 is given as follows. (Although the advertisement procedure is not shown to preserve clarity, you should assume that it applies where appropriate, as described in Section 1.5.1.)
Use Case UC-x: Initiating Actor: Actors Goal: Preconditions: Postconditions: BuyStocks

Player

[full name: investor player] [e.g., Yahoo! Finance]

To buy stocks, get them added to their portfolio automatically

Player is currently logged in the system and is shown a hyperlink Buy stocks.

Participating Actors: StockReportingWebsite

System has informed the player of the purchase outcome. The logs and the players portfolio are updated.

Flow of Events for Main Success Scenario:

1. Player clicks the hyperlink Buy stocks 2. System prompts for the filtering criteria (e.g., based on company names, industry sector, price range, etc.) or Show all 3. Player specifies the filtering criteria and submits 4. System contacts StockReportingWebsite and requests the current stock prices for companies that meet the filtering criteria 5. StockReportingWebsite responds with HTML document containing the stock prices 6. From the received HTML document, System extracts, formats, and displays the stock prices for Players consideration; the display also shows the players account balance that is available for trading 7. Player browses and selects the stock symbols, number of shares, and places the order 8. System (a) updates the players portfolio; (b) adjusts the players account balance, including a commission fee charge; (c) archives the transaction in a database; and (d) informs Player of the successful transaction and shows their new portfolio standing

Notice that in Step 8 above only virtual trading takes place because this is fantasy stock trading.

Ivan Marsic

Rutgers University

112

Derive (a part of) the domain model for the system under development based on the use case BuyStocks. (a) Write a definition for each concept in your domain model. (b) Write a definition for each attribute and association in your domain model. (c) Draw the domain model. (d) Indicate the types of concepts, such as boundary, control, or entity.

Problem 2.15
Suppose you are designing an ATM machine (also see Problem 2.11). Consider the use case Withdraw Cash and finish the sequence diagram shown in Figure 2-27. The CustomerID object contains all the information received from the current customer. IDChecker compares the entered ID with all the stored IDs contained in CustomerIDStorage. AcctInfo mainly contains information about the current account balance. AcctManager performs operations on the AcctInfo, such as subtracting the withdrawn amount and ensuring that the remainder is greater than or equal to zero. Lastly, CashDispenserCtrl control the physical device that dispenses cash. One could argued that AcctInfo and AcctManager should be combined into a single object Account, which encapsulates both account data and the methods that operate on the data. The account data is most likely read from a database, and the container object is created at that time. Discuss the pros and cons for both possibilities.
7
4

2 5 3 8 6 9

: GUI Customer enterCard() askPIN() enterPIN()

: Controller

: CustomerID

: IDChecker

: CustomerIDStore

: AcctInfo

: AcctManager

: CashDispenserCtrl

askAmt() enterAmt()

Figure 2-27: Sequence diagram for the ATM machine of Problem 2.15 (see text for explanation). GUI = Graphical user interface.

Indicate any design principles that you employ in the sequence diagram.

Problem 2.16
You are to develop an online auction site, with selling, bidding, and buying services. The buying service should allow the users to find an item, bid for it and/or buy it, and pay for it. The use case diagram for the system may look as follows:

Chapter 2

Object-Oriented Software Engineering

113

Online Auction Site ListItem include FindItem BidForItem ViewBids CloseAuction BuyItem RateTransaction Creditor
ItemInfo name : String startPrice : float reserved : boolean + + + + + + getName() : String getStartPrice() : float getSeller() : SellerInfo getBidsList() : BidsList setReserved(ok : boolean) isReserved() : boolean seller 1 SellerInfo name : String address : String + getName() : String + getAddress() : String 1 seller Payment amount : float item + getBuyer() : BuyerInfo Etc. buyer + + + + add(bid: Bid) : int remove(idx : int) getNext(): Bid hasMore() : boolean BuyerInfo name : String address : String + getName() : String + getAddress() : String ItemsCatalog

itiat in

initiate

init iate

include

Seller

in itia p te ar tic ipa te

in itia te

initiate te ipa tic ar p tiate i in

Buyer

participate

itia in

te

?
Shipping Agency

Controller

+ + + +

add(item: ItemInfo) : int remove(idx : int) getNext(): ItemInfo hasMore() : boolean

bids 1 BidsList

+ + + + + + +

listItem(item: ItemInfo) findItem(name : String) bidForItem(name : String) viewBids(itemName : String) closeAuction(itmNam : String) buyItem(name : String) payForItem(price: float)

*
Bid amount : float + getBidder() : BuyerInfo + getAmount() : float bidder 1 1

Figure 2-28: A possible class diagram for the online auction site of Problem 2.16.

We assume a simple system to which extra features may be added, such as auction expiration date on items. Other features may involve the shipment agency to allow tracking the shipment status. A possible class diagram for the system is shown in Figure 2-28. Assume that ItemInfo is marked as reserved when the Seller accepts the highest bid and closes the auction on that item only. Before closing, Seller might want to review how active the bidding is, to decide whether to wait for some more time before closing the bid. That particular ItemInfo is removed from ItemsCatalog once the payment is processed. In the use case CloseAuction, the Seller reviews the existing bids for a given item, selects the highest and notifies the Buyer associated with the highest bid about the decision (this is why

Ivan Marsic

Rutgers University

114

participate link between the use case CloseAuction and Buyer). Assume that there are more than one bids posted for the selected item. Complete the interaction diagram shown below for this use case. Do not include processing the payment (for this use case see Problem 2.3). (Note: You may introduce new classes or modify the existing classes in Figure 2-28 if you feel it necessary for solving the problem.)
: Controller Seller viewBids(itemName) ? Buyer

closeAuction(itemName)

Problem 2.17
Consider the use case BuyStocks presented in Problem 2.14. The goal is to draw the UML sequence diagram only for Step 6 in this use case. Start at the point when the system receives the HTML document from the StockReportingWebsite and stop at the point when an HTML page is prepared and sent to players browser for viewing. (a) List the responsibilities that need to be assigned to software objects. (b) Assign the responsibilities from the list in (a) to objects. Explicitly mention any design principles that you are using in your design, such as Expert Doer, High Cohesion, or Low Coupling. Provide arguments as to why the particular principle applies. (c) Draw the UML sequence diagram.

Problem 2.18

Problem 2.19
In the patient-monitoring scenario of Problem 2.9, assume that the hospital personnel who gets notified about patient status is not office-bound but can be moving around the hospital. Also, all notifications must be archived in a hospital database for a possible future auditing. Draw a UML deployment diagram representing the hardware/software mapping of this system.

Problem 2.20

Modeling and System Specification

Chapter 3

Contents
The beginning is the most important part of the work. Plato

3.1 What is a System?

3.1.1 3.1.2 3.1.3 3.1.4 3.1.5 World Phenomena and Their Abstractions States and State Variables Events, Signals, and Messages Context Diagrams and Domains Systems and System Descriptions

Given that the system has different characteristics at different stages of its lifecycle, we need to select a point that the specification refers to. Usually, the system specification states what should be valid (true) about the system at the time when the system is delivered to the customer. Specifying system means stating what we desire to achieve, not how we plan to accomplish it. There are several aspects of specifying the system under development, including: Selecting notation(s) to use for the specification Understanding the problem and determining what needs to be specified Verifying that requirements the specification meets the

3.2 Notations for System Specification

3.2.1 3.2.2 3.2.3 3.2.4 Basic Formalisms for Specifications UML State Machine Diagrams UML Object Constraint Language (OCL) TLA+ Notation

3.3 Problem Frames

3.3.1 Problem Frame Notation 3.3.2 Problem Decomposition into Frames 3.3.3 Composition of Problem Frames 3.3.4

3.4 Specifying Goals

3.4.1 3.4.2 3.4.3 3.4.4

Of course, this does not represent a linear sequence of activities. Rather, as we achieve better understanding of the problem, we may wish to switch to a different notation; also, the verification activity may uncover some weaknesses in understanding the problem and trigger an additional study of the problem at hand.

3.5
3.5.1 3.5.2 3.5.3

3.6 Summary and Bibliographical Notes Problems

We have already encountered one popular notation for specification, that is, the UML standard. We will continue using UML and learn some more about it as well as about some other notations. Most developers agree that a single type of system model is not enough to specify any non-trivial system. You usually need several different models, told in different languages for different stakeholders. The end user has certain requirements about the system, such as that the system allows them to do their job easier. The business manager may be more concerned about the policies, rules, and processes supported by the system. Some stakeholders will care about engineering designs details, and others will not. Therefore, it is advisable to develop the system specification as viewed from several different angles, using different notations.

115

Ivan Marsic

Rutgers University

116

My primary concern here is the developers perspective. We need to specify what are the resting/equilibrium states and the anticipated perturbations. How does the system appear in an equilibrium state? How does it react to a perturbation and what sequence of steps it goes through to reach a new equilibrium? We already saw that use cases deal with such issues, to a certain extent, although informally. Here, I will review some more precise approaches. This does not necessarily imply formal methods; rather, the goal is to work with a certain degree of precision that is amenable to some form of analysis. The system specification should be derived from the requirements. The specification should accurately describe the system behavior necessary to satisfy the requirements. Many a developer would argue that the hardest part of software task is arriving at a complete and consistent specification, and much of the essence of building a program is in fact the debugging its specificationfiguring out what exactly needs to be done. The problem is that the requirements are often fuzzy or incomplete. I should emphasize again and again that writing the requirements and deriving the specification is not a strictly sequential process. Rather, we must explore the requirements and system specification iteratively, until a satisfactory solution is found. Even then, we may need to revisit and reexamine both if questions arise during the design and implementation. Although the system requirements are ultimately decided by the customer, the developer needs to know how to ask the right questions and how to systemize the information gathered from the customer. But, what questions to ask? A useful approach would be to be start with a catalogue of simple representative problems that tend to occur in every real-world problem. These elementarybuilding-block problems are called problem frames. Each can be described in a well-defined format, each has a well-known solution, and each has a well-known set of associated issues. In Section 3.3 we will see how complex problems can be made manageable by applying problem frames. In this way, problem frames can help us bridge the gap between system requirements and system specification.

3.1 What is a System?

All models are wrong, but some are useful. George E. P. Box There is no property absolutely essential to one thing. The same property, which figures as the essence of a thing on one occasion, becomes a very inessential feature upon another. William James

In Chapter 2 we introduced system under discussion (SuD) as the software product that a software engineer (or a team of engineers) sets out to develop. The rest of the world (environment) has been of concern only as far as it interacts with the SuD and it was abstracted as a set of actors. By describing different interaction scenarios as a set of use cases, we were able to develop a software system in an incremental fashion. However, there are some limitations with this approach. First, by considering only the actors that the system directly interacts with, we may leave out some parts of the environment that have no direct interactions with the SuD but are important to the problem and its solution. Consider, for example, the stock market fantasy league system and the context within which it operates

Chapter 3

Modeling and System Specification

117

(Figure 1-24). Here, the real-world stock market exchange does not interact with our SuD, so it would not be considered an actor. Conceivably, it would not even be mentioned in any of the use cases, because it is neither initiating nor participating actor! I hope that the reader would agree that this is strangethe whole project revolves about a stock exchange and yet the stock exchange may not appear in the system description at all. Second, starting with the focus on interaction scenarios may not be the easiest route in describing the problem. Use cases describe the sequence of users (actor) interaction with the system. I already mentioned that use cases are procedural rather than object-oriented. The focus on sequential procedure may not be difficult to begin with, but it requires being on a constant watch for any branching off of the main success scenario. Decision making (branching points) may be difficult, particularly if not guided by a helpful representation of the problem structure. The best way to start conceptual modeling may be with how users and customers prefer to conceptualize their world, because the developer needs to have great deal of interaction with customers at the time when the problem is being defined. This may also vary across different application domains. In this chapter I will present some alternative approaches to problem description (requirements and specification), which may be more involved but I believe offer easier routes to solving largescale and complex problems.

3.1.1

World Phenomena and Their Abstractions

The key to solving a problem is in understanding the problem. Because problems are in the real world, we need good abstractions of world phenomena. Good abstractions will help us to represent accurately the knowledge that we gather about the world (that is, the application domain, as it relates to our problem at hand). In object-oriented approach, key abstractions are objects and messages and they served us well in Chapter 2 in understanding the problem and deriving the solution. We are not about to abandon them now; rather, we will broaden our horizons and perhaps take a slightly different perspective. Usually we partition the world in different parts (or regions, or domains) and consider different phenomena, see Figure 3-1. A phenomenon is a fact, or object, or occurrence that appears or is perceived to exist, or to be present, or to be the case, when you observe the world or some part of it. We can distinguish world phenomena by different criteria. Structurally, we have two broad categories of phenomena: individuals and relations among individuals. Logically, we can distinguish causal vs. symbolic phenomena. In terms of behavior, we can distinguish deterministic vs. stochastic phenomena. Next I describe each kind briefly. I should like to emphasize that this is only one possible categorization, which seems suitable for software engineering; other categorizations are possible and have been proposed. Moreover, any specific identification of world phenomena is evanescent and bound to become faulty over time, regardless of the amount of effort we invest in deriving it. I already mentioned in Section 0 the effect of the second law of thermodynamics. When identifying the world phenomena, we inevitably make approximations. Certain kinds of information are regarded as important and the rest of the information is treated as unimportant and ignored. Due to the random fluctuations in the nature, some of the phenomena that served as the basis for our separation of important and

Ivan Marsic

Rutgers University

118

WORLD

Part/Domain I

Part/Domain J

Phenomena in Part i

Phenomena in Part j Shared phenomena

Phenomena in Part k

Part/Domain K

Figure 3-1: World partitioning into domains and their phenomena.

unimportant information will become intermingled thus invalidating our original model. Hence the ultimate limits to what our modeling efforts can achieve.

Individuals
An individual is something that can be named and reliably distinguished from other individuals. Decisions to treat certain phenomena as individuals are not objectivethey depend on the problem at hand. It should be clear by now that the selected level of abstraction is relative to the observer. We choose to recognize just those individuals that are useful to solving the problem and are practically distinguishable. We will choose to distinguish three kinds of individual: events, entities, and values. An event is an individual happening, occurring at a particular point in time. Each event is indivisible and instantaneous, that is, the event itself has no internal structure and takes no time to happen. Hence, we can talk about before the event and after the event, but not about during the event. An example event is placing a trading order; another example event is executing a stock trading transaction; yet another example is posting a stock price quotation. Further discussion of events is in Section 3.1.3. An entity is an individual with distinct existence, as opposed to a quality or relation. An entity persists over time and can change its properties and states from one point in time to another. Some entities may initiate events; some may cause spontaneous changes to their own states; some may be passive. Software objects and abstract concepts modeled in Chapter 2 are entities. But entities also include real-world objects. The entities are determined by what part of the world is being modeled. A financial-trader in our investment assistant case study (Section 1.3.2) is an entity; so is his or her investment-portfolio; a listed-stock is also an entity. They belong to entity classes trader, portfolio, and stock, respectively.

Chapter 3

Modeling and System Specification

119

Set of all pairs of persons

Set of all 3-tuples of persons

Set of love triangles

(a)

Set of neighbors

(b)

Figure 3-2: Example relations: Neighbors(Person_i, Person_j) and InLoveTriangle(Person_i, Person_j, Person_k).

A value is an intangible individual that exists outside time and space, and is not subject to change. The values we are interested in are such things as numbers and characters, represented by symbols. For example, a value could be the numerical measure of a quantity or a number denoting amount on some conventional scale. In our case study (Section 1.3.2), a particular stock price is a number of monetary units in which a stock share is pricedand is therefore a value. Examples of value classes include integer, character, string, and so on.

Relations
We say that individuals are in relation if they share a certain characteristic. To define a relation, we also need to specify how many individuals we consider at a time. For example, for any pair of people, we could decide that they are neighbors if their homes are less than 100 meters apart from each other. Given any two persons, Person_i and Person_j, if they pass this test the relation holds (is true); otherwise it does not hold (is false). All pairs of persons that pass the test are said to be in the relation Neighbors(Person_i, Person_j). The pairs of persons that are neighbors form a subset of all pairs of persons as shown in Figure 3-2(a). Relations need not be established on pairs of individuals only. We can consider any number of individuals and decide whether they are in relation. The number n of considered individuals can be any positive integer n 2 and it must be fixed for every test of the relation; we will call it an ntuple. We will write relation as RelationName(Individual1, , Individualn). When one of the individuals remains constant for all tests of the relation, we may include its name in the relations name. For example, consider the characteristic of wearing eyeglasses. Then we can test whether a Person_i is in relation Wearing(Person_i, Glasses), which is a subset of all persons. Because Glasses remain constant across all tests, we can write WearingGlasses(Person_i), or simply Bespectacled(Person_i). Consider next the so-called love triangle relation as an example for n = 3. Obviously, to test for this characteristic we must consider exactly three persons at a time; not two, not four. Then the relation InLoveTriangle(Person_i, Person_j, Person_k) will form a set of all triplets (3-tuples) of persons for whom this characteristic is true, which is a subset of all 3tuples of persons as shown in Figure 3-2(b). A formal definition of relation will be given in Section 3.2.1 after presenting some notation. We will consider three kinds of relations: states, truths, and roles.

Ivan Marsic

Rutgers University

120

A state is a relation among individual entities and values, which can change over time. I will describe states in Section 3.1.2, and skip them for now. A truth is a fixed relation among individuals that cannot possibly change over time. Unlike states, which change over time, truths remain constant. A bit more relaxed definition would be to consider the relations that are invariable at the time-scale that we are interested in. Example timescales could be project duration or anticipated product life-cycle. When stating a truth, the individuals are always values, and the truth expresses invariable facts, such as GreaterThan(5, 3) or StockTickerSymbol(Google, Inc., GOOG). It is reasonably safe to assume that company stock symbols will not change (although mergers or acquisitions may affect this?). A role is a relation between an event and individual that participate in it in a particular way. Each role expresses what you might otherwise think of as one of the arguments (or parameters) of the event.

Causal vs. Symbolic Phenomena

Causal phenomena are events, or roles, or states relating entities. These are causal phenomena because they are directly produced or controlled by some entity, and because they can give rise to other phenomena in turn. Symbolic phenomena are values, and truths and states relating only values. They are called symbolic because they are used to symbolize other phenomena and relationships among them. A symbolic state that relates valuesfor example, the data content of a disk recordcan be changed by external causation, but we do not think of it as causal because it can neither change itself nor cause change elsewhere.

Deterministic vs. Stochastic Phenomena

Deterministic phenomena are the causal phenomena for which the occurrence or nonoccurrence can be established with certainty. Stochastic phenomena are the causal phenomena that are governed by a random distribution of probabilities.

3.1.2

States and State Variables

A state describes what is true in the world at each particular point in time. The state of an individual represents the cumulative results of its behavior. Consider a device, such as a compact disc (CD) player. How the device reacts to an input command depends not only upon that input, but also upon the internal state that the device is currently in. So, if the PLAY button is pushed on a CD player, what happens next will depend on various things, such as whether or not the player is turned on, contains a CD, or is already playing. These conditions represent different states of a CD player. By considering such options, we may come up with a list of all states for a CD player, like this: State 1: NotPowered State 2: Powered (the player is not powered up) (the player is powered up)

Chapter 3

Modeling and System Specification

121

State 3: Loaded State 4: Playing

(a disc is in the tray)

We can define state more precisely as a relation on a set of objects, which simply selects a subset of the set. For the CD player example, what we wish to express is The CD players power is off. We could write Is(CDplayer, NotPowered) or IsNotPowered(CDplayer). We will settle on this format: NotPowered(CDplayer). NotPowered(x) is a subset of CD players x that are not powered up. In other words, NotPowered(x) is true if x is currently off. Assuming that one such player is the one in the living room, labeled as CDinLivRm, then NotPowered(CDinLivRm) holds true if the player in the living room is not powered up. Upon a closer examination, we may realize that the above list of states implies that a nonpowered-up player never contains a disc in the tray. If you are charged to develop software for the CD player, you must clarify this. Does this mean that the disc is automatically ejected when the power-off button is pushed? If this is not the case or the issue is yet unresolved, we may want to redesign our list of CD player states as: State 1: NotPoweredEmpty State 2: NotPoweredLoaded State 3: PoweredEmpty State 4: PoweredLoaded State 5: Playing (the player is not powered up and it contains no disc) (the player is not powered up but with a disc is in the tray) (the player is powered up but it contains no disc) (the player is powered up and a disc is in the tray)

At this point one may realize that instead of aggregate or global system states it may be more elegant to discern different parts (sub-objects) of the CD player and, in turn, consider the state of each part (Figure 3-3). Each part has its local states, as in this table System part (Object) State relations Power button {Off, On} Disc tray {Empty, Loaded} Play button {Off, On} Notice that the relation Off(b) is defined on the set of buttons. Then these relations may be true: Off(PowerButton) and Off(PlayButton). Similar holds for On(b). Given the states of individual parts, how can we define the state of the whole system? Obviously, we could say that the aggregate system state is defined by the states of its parts. For example, one state of the CD player is { On(PowerButton), Empty(), Off(PlayButton), }. Notice that I left the relation Empty() without an argument, because it is clear to which object it refers to. In this case we could also write Empty without parentheses. The arrangement of the relations in this state tuple is not important as long as it is clear what part each relation refers to. The question now arises, is every combination of parts states allowed? Are these parts independent of each other or there are constraints on the state of one part that are imposed by the current states of other parts? Some states of parts of a composite domain may be mutually exclusive. Going back to the issue posed earlier, can the disc tray be in the loaded state when the power button is in the off state? Because these are parts of the same system, we must make explicit any mutual dependencies of the parts states. We may end up with a list of valid system state tuples that does not include all possible tuples that can be constructed.

Ivan Marsic

Rutgers University

122

CD player Power button Disc tray

CD player

Play button

(b)

(a)

Figure 3-3: Abstractions of a CD player at different levels of detail: (a) The player as a single entity. (b) The player seen as composed of several entities.

Both representations of a system state (single aggregate state vs. tuple of parts states) are correct, but their suitability depends on what kind of details you care to know about the system. In general, considering the system as a set of parts that define state tuples presents a cleaner and more modular approach than a single aggregate state. In software engineering, we care about the visible aspects of the software system. In general, visible aspects do not necessarily need to correspond to parts of the system. Rather, they are any observable qualities of the system. For example, domain-model attributes identified in Section 2.4 represent observable qualities of the system. We call each observable quality a state variable. In our first case-study example, variables include the lock and the bulb. Another variable is the counter of the number of trials at opening the lock. Yet another variable is the amount of timer that counts down the time elapsed since the lock was open, to support auto-lock functionality. The state variables of our system can be summarized as in this table Variable State relations Door lock {Disarmed, Armed} Bulb {Lit, Unlit} Counter of failed trials {0, 1, , maxNumOfTrials} Auto-lock timer {0, 1, , autoLockLimit} In case of multiple locks and/or bulbs, we have a different state variable for every lock/bulb, similar to the above example of CD player buttons. So, the state relations for backyard and front door locks could be defined as Disarmed(Backyard) and Disarmed(Front). The situation with numeric relations is a bit trickier. We could write 2(Counter) to mean that the counter is currently in state 2, but this is a bit awkward. Rather, just for the sake of convenience I will write Equals(Counter, 2) and similarly Equals(Timer, 3).
System state is defined as a tuple of state variables containing any valid combination of state relations. State is an aggregate representation of the system characteristics that we care to know about looking from outside of the system. For the above example, an example state tuple is: { Disarmed(Front), Lit, Armed(Backyard), Equals(Counter, 0), Equals(Timer, 0) }.

One way to classify states is by what the object is doing in a given state: A state is a passive quality if the object is just waiting for an event to happen. For the CD player described earlier, such states are Powered and Loaded.

Chapter 3

Modeling and System Specification

123

A state is an active quality if the object is executing an activity. When the CD player is in the Playing state it is actively playing the CD.

A combination of these options is also possible, i.e., the object may be executing an activity and also waiting for an event. The movements between states are called transitions and are most often caused by events (described in Section 3.1.3). Each state transition connects two states. Usually, not all pairs of states are connected by transitionsonly specific transitions are permissible.
Example 3.1 Identifying Stock Exchange States (First Attempt)

Consider our second case study on an investment assistant system (Section 1.3.2), and suppose that we want to identify the states of the stock exchange. There are many things that we can say about the exchange, such as where it is located, dimensions of the building, the date it was built, etc. But, what properties we care to know as it relates to our problem? Here are some candidates: What are the operating hours and is the exchange currently open or closed? What stocks are currently listed? For each listed stock, what are the quoted price (traded/bid/ask) and the number of offered shares? What is the current overall trading volume? What is the current market index or average value? State relations {Open, Closed} any positive real number {0, 1, 2, 3, } {0, 1, 2, 3, } any positive real number

The state variables can be summarized like so: Variable Operating condition (or gate condition) ith stock price ith stock number of offered shares Trading volume Market index/average

The asterisk in the table indicates that the prices are quoted up to a certain number of decimal places and there is a reasonable upper bound. In other words, this is a finite set of finite values. Obviously, this system has a great many of possible states, which is, nonetheless, finite. An improvised graphical representation is shown in Figure 3-4. (UML standard symbols for state diagrams are described later in Section 3.2.2.) An example state tuple is: { Open, Equals(Volume, 783014), Equals(Average, 1582), Equals(Price_1, 74.52), Equals(Shares_1, 10721), Equals(Price_2, 105.17), Equals(Shares_2, 51482), }. Notice that the price and number of shares must be specified for all the listed stocks. As the reader should know by now, the selection of state phenomena depends on the observer and observers problem at hand. An alternative characterization of a market state is presented later in Example 3.2.

Ivan Marsic

Rutgers University

124

Market gate

Market index Open Closed 1.00 1.01 1.02

Stock_1_Price

Stock_1_Shares

Stock_2_Price

Stock_2_Shares

1.00

1.00

1.01

1.01

1.02

1.02

3 ( prices and num. of shares for all listed stocks )

Figure 3-4: Graphical representation of states for Example 3.1. The arrows indicate the permissible paths for transitioning between different states.

Observables vs. Hidden Variables States Defined from Observable Phenomena State is an abstraction, and as such it is subjectiveit depends on who is making the abstraction. There are no objective statesevery categorization of states is relative to the observer. Of course, the same observer can come up with different abstractions. The observer can also define new states based on observable phenomena; such states are directly observed. Consider, for example, a fruit states: green, semiripe, ripe, overripe, and rotten. The state of ripeness of a fruit is defined based on observable parameters such as its skin color and texture, size, scent, softness on touch, etc. Similarly, a moving state of an elevator is defined by observing its position over subsequent time moments and calculating the trend. For the auto-lock timer discussed earlier, we can define the states CountingDown and Idle like so: CountingDown(Timer) Idle(Timer) The symbol
=

The relation Equals(Timer, ) holds true for decreasing with time

The relation Equals(Timer, ) holds true for remaining constant with time means that this is a defined state.
Identifying Stock Exchange States (Second Attempt)

Example 3.2

Let us revisit Example 3.1. Upon closer examination, one may conclude that the trader may not find very useful the variables identified therein. In Section 1.3.2, we speculated that what trader really cares about is to know if a trading opportunity arises and, once he or she places a trading order, tracking the status of the order. Let us assume that the trading decision will be made based on the trending direction of the stock price. Also assume that, when an upward trend of Stock_is price triggers a decision to

Chapter 3

Modeling and System Specification

125

OrderPending x2 x1 x x+1 x+2

OrderExecuted

Figure 3-5: Graphical representation of states for Example 3.2. Microstates from Figure 3-4 representing the number of offered shares are aggregated into two macrostates.
buy, a market order is placed for x shares of Stock_i. To summarize, the trader wants to represent the states of two things: Stock tradability states (buy, sell, hold) are defined based on considering a time window of recent prices for a given stock and interpolating a line. If the line exhibits an upward trend, the stock state is Buy. The states Sell and Hold are decided similarly. A more financially astute trader may use some of the technical analysis indicators (e.g., Figure 1-19), instead of the simple regression line. Order status states (pending vs. executed) are defined based on whether there are sufficient shares offered so the buying transaction can be carried out. We have to be careful here, because a selling transaction can be executed only if there are willing buyers. So, the buy and sell orders have the same states, defined differently.

Then the trader could define the states of the market as follows: Buy = The regression line of the relation Equals(Price_i(t), p), for t = tcurrent Window, , tcurrent 2, tcurrent 1, tcurrent, has a positive slope Sell = The regression line of the relation Equals(Price_i(t), p), for t = tcurrent Window, , tcurrent, has a negative slope Hold = The regression line of the relation Equals(Price_i(t), p), for t = tcurrent Window, , tcurrent, has a zero slope SellOrderPending = The relation Equals(Shares_i, y) holds true for all values of y less than x SellOrderExecuted = The relation Equals(Shares_i, y) holds true for all values of y greater than or equal to x What we did here, essentially, is to group a large number of detailed states from Example 3.1 into few aggregate states (see Figure 3-5). These grouped states help simplify the traders work. It is possible to discern further nuances in each of these states. For example, two sub-states of the state Sell could be distinguished as when the trader should sell to avert greater loss vs. when they may wish to take profit at a market top. The most important point to keep in mind is the traders goals and strategies for achieving them. This is by no means the only way the trader could view the market. A more proficient trader may define the states in terms of long vs. short trading positions (see Section 1.3.2, Figure 1-18). Example states could be: GoLong The given stock is currently suitable for taking a long position GoShort The given stock is currently suitable for taking a long position GoNeutral The trader should hold or avoid the given stock at this time

Ivan Marsic

Rutgers University

126

The states that are directly observable at a given level of detail (coarse graining) will be called microstates. A group of microstates is called a macrostate (or superstate). The states defined in Example 3.2 are macrostates. Sometimes our abstraction may identify simultaneous (or concurrent) activities that object executes in a given state. For example, when the CD player is in the Playing state it may be simultaneously playing the CD (producing audio sounds) and updating the time-progress display. Section 3.2.2 describes UML state machine diagrams as a standardized graphical notation for representing states and transitions between them.

3.1.3

Events, Signals, and Messages

Event definition requires that events are indivisibleany happening (or performance, or action) that has an internal time structure must be regarded as two or more events. The motivation for this restriction is to avoid having intermediate states: an event represents a sharp boundary between two different states. We also need to assume that no two events occur simultaneously. All events happen sequentially, and between successive events there are intervals of time in which nothing happensthat is, there are no events. Events and intervals alternate: each event ends one interval and begins another. The developer may need to make a choice of what to treat as a single event. Consider the homeaccess control case study (Section 1.3.1). When the tenant is punching in his or her identification key, should this be treated as a single event, or should each keystroke be considered a different event? The answer depends on whether your problem statement requires you to treat it one way or another. Are there any exceptions, which are relevant to the problem, that may arise between different keystrokes? If so, then we need to treat each keystroke as an event. The reader may wonder about the relationship between events and messages or operations in object oriented approach. The notion of event as defined above is more general, because it is not limited to object orientation. The notion of message implies that a signal is sent from one entity to another. Unlike this, and event is something that happensit may include one or more individuals but it is not necessarily directed from one individual to another. Events just mark transitions between successive events. The advantage of this view is that we can avoid specifying processing detail at an early stage of problem definition. Unlike this, use case scenarios require making explicit the sequential processing procedure, which leads to system operations (Section 2.3.3Error! Reference source not found.). Another difference is that events always signify state changeeven for the cases where system remains in the same state, there is an explicit description of an event and state change. Hence, events depend on how the corresponding state set is already defined. Unlike this, messages may not be related to state changes. For example, an operation that simply retrieves the value of an object attribute (known as accessor operation) does not affect the objects state. Example events: listStock this event marks that it is first time available for trading marks transition between price states; marks a transition between number-of-shares-available states

Chapter 3

Modeling and System Specification

127

submit

matched

archive

InPreparation

Pending

Executed

Archived

Figure 3-6: Graphical representation of events marking state transitions of a trading order.

splitStock this event marks a transition between price states; marks transition between numberof-shares-available states submitOrder this event marks a transition between the states of a trading order; also marks a transition between price states (the indicative price of the stock gets updated); also marks a transition between number-of-shares-available states, in case of a sell-order matchFound this event marks a transition between the states of a trading order when a matching order(s) is(are) found; also marks a transition between price states (the traded price of the stock gets updated); also marks a transition between number-of-shares-available states The above events can also mark change in trading volume and market index/average. The reader may have noticed that I prefer to form event names as verb phrases. The reason for this is to distinguish events from states. Although this is reminiscent of messages in object-oriented approach, events do not necessarily correspond to messages, as already discussed earlier.
Example 3.3 Identifying Stock Exchange Events

Consider Example 3.2, where the states Buy, Sell, or Hold, are defined based on recent price movements. The events that directly lead to transitioning between these states are order placements by other traders. There may be many different orders placed until the transition happens, but we view the transitioning as an indivisible eventthe moment when the regression line slope exceeds a given threshold value. The events can be summarized like so: Event Description trade Causes transition between stock states Buy, Sell, or Hold submit Causes transition between trading-order states InPreparation OrderPending matched Causes transition between trading-order states OrderPending OrderExecuted The events marking a trading order transitions are shown in Figure 3-6. Other possible events include bid and offer, which may or may not lead to transitions among the states of a trading order. We will consider these in Section 3.2.2.

3.1.4

Context Diagrams and Domains

Now that we have defined basic phenomena, we can start by placing the planned system in a contextthe environment in which it will work. For this we use context diagrams, which are

Ivan Marsic

Rutgers University

128

Investment portfolio

Trading order

Context diagram symbols:

A box with a double stripe is a machine domain

Trader

Machine (SuD)

Stock exchange

A box with a single stripe is a designed domain

ith stock Bank

A box with no stripe is a given domain

Figure 3-7: Context diagram for our case study 2: investment advisory system.

essentially a bit more than the commonplace block diagrams. I should mention that context diagrams are not part of UML; they were introduced by Michael Jackson [1995] based on the notation dating back to structured analysis in 1970s. The context diagram represents the context of the problem that the developer sets out to solve. The block diagrams we encountered in Figure 1-16(b) and Figure 1-24 are essentially context diagrams. Essentially, given the partitioning shown in Figure 3-1, we show different domains as rectangular boxes and connect them with lines to indicate that they share certain phenomena. Figure 3-7 is Figure 1-16(b) redrawn as a context diagram, with some more details added. Our system, labeled machine (or SuD), subsumes the brokers role and the figure also shows abstract concepts such as portfolio, trading order, and ith stock. Jackson uses the term machine in an effort to get around the ambiguities of the word system, some of which were discussed in Section 2.3.2. The reader who rather prefers SuD is free to use it. A context diagram shows parts of the world (Figure 3-1) that are relevant to our problem and only the relevant parts. Each box in a context diagram represents a different domain. A domain is a part of the world that can be distinguished because it is conveniently considered as a whole, and can be consideredto some extentseparately from other parts of the world. Each domain is a different subject matter that appears in the description of the problem. A domain is described by the phenomena that exist or occur in it. In every software development problem there are at least two domains: the application domain (or environment, or real worldwhat is given) and the machine (or SuDwhat is to be constructed). The reader may notice that some of the domains in Figure 3-7 correspond to what we called actors in Chapter 2. However, there are other subject matters, as well, such as Investment portfolio. To simplify our considerations, we decide that all the domains in the context diagram are physical. In Figure 3-7, while this may be clear for other domains, even Investment portfolio should be a physical domain. This is achieved by taking this box to stand for the physical representation of the information about the stocks that the trader owns. In other words, this is the representation stored in computer memory (e.g., on hard disk) or displayed on a screen or printed on paper. The reason for emphasizing physical domains and physical interactions is because the point of software development is to build systems that interact with the physical world and change it.

Chapter 3

Modeling and System Specification

129

enable disable

Play button notify start stop

activate shut down Disc tray eject (?)

Power button eject load

activate shut down Display

enable disable

notify Eject button

Figure 3-8: Domains and shared phenomena in the problem of controlling a CD player.

Domain Types
Domains can be distinguished as to whether they are given or are to be designed. A given domain is a problem domain whose properties are givenwe are not allowed to design such a domain. In some cases the machine can influence the behavior of a given domain. For example, in Figure 3-7 executing trading orders influences the behavior of the stock exchange (given domain). A designed domain is a problem domain for which data structures and, to some extent, its data content need to be determined and constructed. An example is the Investment portfolio domain in Figure 3-7. Often, one kind of problem is distinguished from another by different domain types. To a large degree these distinctions arise naturally out of the domain phenomena. But it is also useful to make a broad classification into three main types. A causal domain is one whose properties include predictable causal relationships among its causal phenomena. A causal domain may control some or all or none of the shared phenomena at an interface with another domain. A biddable domain usually consists of people. The most important characteristic of a biddable domain is that it lacks positive predictable internal causality. That is, in most situations it is impossible to compel a person to initiate an event: the most that can be done is to issue instructions to be followed. A lexical domain is a physical representation of datathat is, of symbolic phenomena.

Shared Phenomena
So far we considered world phenomena as belonging to particular domains. Some phenomena are shared. Shared phenomena, viewed from different domains, are the essence of domain interaction and communication. You can think of the domains as seeing the same event from different points of view. Figure 3-8 shows

Ivan Marsic

Rutgers University

130

3.1.5

Systems and System Descriptions

Now that we have defined domains as distinguishable parts of the world, we can consider any domain as a system. A system is an organized or complex whole, an assemblage of things or parts interacting in a coordinated way. All systems are affected by events in their environment either internal and under the organizations control or external and not controllable by the organization. Behavior under Perturbations: We need to define the initial state, other equilibrium states, and state transitions. Most of real-world problems require a dynamical model to capture a process which changes over time. Depending on the application, the particular choice of model may be continuous or discrete (using differential or difference equations), deterministic or stochastic, or a hybrid. Dynamical systems theory describes properties of solutions to models that are prevalent across the sciences. It has been quite successful, yielding geometric descriptions of phase portraits that partition state space into region of solution trajectories with similar asymptotic behavior, characterization of the statistical properties of attractors, and classification of bifurcations marking qualitative changes of dynamical behavior in generic systems depending upon parameters. [Strogatz, 1994] S. Strogatz, Nonlinear Dynamics and Chaos: With Applications to Physics, Biology, Chemistry and Engineering. Perseus Books Group, 1994. Given an external perturbation or stimulus, the system responds by traversing a set of transient states until it settles at an equilibrium state. An equilibrium state may involve stable oscillations, e.g., a behavior driven by an internal clock. In mechanics, when an external force acts on an object, we describe its behavior through a set of mathematical equations. Here we describe it as a sequence of (discrete) action-reaction or stimulus-response events, in plain English. Figure 3-x shows the state transition diagram. Action turnLightOff is marked with question mark because we are yet to arrive at an acceptable solution for this case. The state [disarmed, unlit] is not shown because the lock is not supposed to stay for a long in a disarmed stateit will be closed shortly either by the user or automatically.

3.2 Notations for System Specification

psychologically we must keep all the theories in our heads, and every theoretical physicist who is any good knows six or seven different theoretical representations for exactly the same physics. He knows that they are all equivalent, and that nobody is ever going to be able to decide which one is right at that level, but he keeps them in his head, hoping that they will give him different ideas for guessing. Richard Feynman, The Character of Physical Law

Chapter 3

Modeling and System Specification

131

3.2.1

Basic Formalisms for Specifications

You can only find truth with logic if you have already found truth without it. Gilbert Keith Chesterton, The Man who was Orthodox Logic: The art of thinking and reasoning in strict accordance with the limitations and incapacities of the human misunderstanding. Ambrose Bierce, The Devils Dictionary

This section reviews some basic discrete mathematics that often appears in specifications. First I present a brief overview of sets notation. A set is a well-defined collection of objects that are called members or elements. A set is completely defined by its elements. To declare that object x is a member of a set A, write x A. Conversely, to declare that object y is not a member of a set A, write x A. A set which has no members is the empty set and is denoted as { } or . Sets A and B are equal (denoted as A = B) if they have exactly the same members. If A and B are not equal, write A B. A set B is a subset of a set A if all of the members of B are members of A, and this is denoted as B A. The set B is a proper subset of A if B is a subset of A and B A, which is denoted as B A. The union of two sets A and B is the set whose members belong to A, B or both, and is denoted as A B. The intersection of two sets A and B is the set whose members belong to both A and B, and is denoted as A B. Two sets A and B are disjoint if their intersections is the empty set: A B = . When B A, the set difference A \ B is the set of members of A which are not members of B. The members of a set can themselves be sets. Of particular interest is the set that contains all of the subsets of a given set A, including both and A itself. This set is called the power set of set A and is denoted (A), or A, or 2A. The ordered pair x, y is a pair of objects in which x is the first object and y is the second object. Two ordered pairs x, y and a, b are equal if and only if x = a and y = b. We define Cartesian product or cross product of two sets A and B (denoted as A B) as the set of all ordered pairs x, y where x A and y B. We can define the n-fold Cartesian product as A A A. Recall the discussion of relations among individuals in Section 3.1.1. An n-ary relation R on A, for n > 1, is defined as a subset of the n-fold Cartesian product, R A A A.

Boolean Logic
The rules of logic give precise meaning to statements and so they play a key role in specifications. Of course, all of this can be expressed in a natural language (such as English) or you can invent your own syntax for describing the system requirements and specification. However, if these descriptions are expressed in a standard and predictable manner, not only they can be easily understood, but also automated tools can be developed to understand such descriptions. This allows automatic checking of descriptions. Propositions are the basic building block of logic. A proposition is a declarative sentence (a sentence that declares a fact) that is either true or false, but not both. We already saw in Section 1.3 how a proposition is a statement of a relation among concepts, given that the truth value of the statement is known. Examples of declarative sentence are Dogs are mammals and one plus one equals three. The first proposition is true and the second one is false. The sentence Write this down is not a proposition because it is not a declarative sentence. Also, the sentence x is

Ivan Marsic

Rutgers University

132

Table 3-1: Operators of the propositional and predicate logics. Propositional Logic conjunction (p and q) implication (if p then q) disjunction (p or q) biconditional (p if and only if q) negation (not p) equivalence (p is equivalent to q) Predicate Logic (extends propositional logic with the two quantifiers) universal quantification (for all x, P(x)) existential quantification (there exists x, P(x))

smaller than five is not a proposition because it is neither true nor false (depends on what x is). The conventional letters used to denote propositions are p, q, r, s, These are called propositional variables or statement variables. If a proposition is true, its truth value is denoted by T and, conversely, the truth value of a false proposition is denoted by F. Many statements are constructed by combining one or more propositions, using logical operators, to form compound propositions. Some of the operators of propositional p q pq logic are shown on top of Table 3-1. T T T A conditional statement or, simply a conditional, is obtained by combining T F F two propositions p and q to a compound proposition if p, then q. It is also F T T written as p q and can be read as p implies q. In the conditional F F T statement p q, p is called the premise (or antecedent or hypothesis) and q is called the conclusion (or consequence). The conditional statement p q Truth table is false when the premise p is true and the conclusion q is false, and true for p q. otherwise. It is important to note that conditional statements should not be interpreted in terms of cause and effect. Thus, when we say if p, then q, we do not mean that the premise p causes the conclusion q, but only that when p is true, q must be true as well12. The statement p q is a biconditional, or bi-implication, which means that p q and q p. The biconditional statement p q is true when p and q have the same truth value, and is false otherwise. So far we have considered propositional logic; now let us briefly introduce predicate logic. We saw ealier that the sentence x is smaller than 5 is not a proposition because it is neither true nor false. This sentence has two parts: the variable x, which is the subject, and the predicate, is smaller than 5, which refers to a property that the subject of the sentence can have. We can denote this statement by P(x), where P denotes the predicate is smaller than 5 and x is the variable. The sentence P(x) is also said to be the value of the propositional function P at x. Once a specific value has been assigned to the variable x, the statement P(x) becomes a proposition and has a truth value. In our example, by setting x = 3, P(x) is true; conversely, by setting x = 7, P(x) is false13.

12

This is different from the if-then construction used in many programming languages. Most programming languages contain statements such as if p then S, where p is a proposition and S is a program segment of one or more statements to be executed. When such an if-then statement is encountered during the execution of a program, S is executed is p is true, but S is not executed if p is false. The reader might have noticed that we already encountered predicates in Section 3.1.2 where the state relations for objects actually are predicates.

13

Chapter 3

Modeling and System Specification

133

There is another way of creating a proposition from a propositional function, called quantification. Quantification expresses the extent to which a predicate is true over a range of elements, using the words such as all, some, many, none, and few. Most common types of quantification are universal quantification and existential quantification, shown at the bottom of Table 3-1. The universal quantification of P(x) is the proposition P(x) is true for all values of x in the domain, denoted as x P(x). The value of x for which P(x) is false is called a counterexample of x P(x). The existential quantification is the proposition There exists a value of x in the domain such that P(x) is true, denoted as x P(x). In constructing valid arguments, a key elementary step is replacing a statement with another statement of the same truth value. We are particularly interested in compound propositions formed from propositional variables using logical operators as given in Table 3-1. Two types of compound propositions are of special interest. A compound proposition that is always true, regardless of the truth values of its constituent propositions is called a tautology. A simple example is p p, which is always true because either p is true or it is false. On the other hand, a compound proposition that is always false is called a contradiction. A simple example is p p, because p cannot be true and false at the same time. Obviously, the negation of a tautology is a contradiction, and vice versa. Finally, compound proposition that is neither a tautology nor a contradiction is called a contingency. The compound propositions p and q are said to be logically equivalent, denoted as p q, if p q is a tautology. In other words, p q if p and q have the same truth values for all possible truth values of their component variables. For example, the statements r s and r s are logically equivalent, which can be shown as follows. Earlier we stated that a conditional statement is false only when its premise is true and its conclusion is false, and true otherwise. We can write this as r s (r s) r (s) r s by the first De Morgans law: (p q) p q

[For the sake of completeness, I state here, as well, the second De Morgans law: (p q) p q.] Translating sentences in natural language into logical expressions is an essential part of specifying systems. Consider, for example, the following requirements in our second case study on financial investment assistant (Section 1.3.2).
Example 3.4 Translating Requirements into Logical Expressions

Translate the following two requirements for our second case study on personal investment assistant (Table 2-2) into logical expressions: REQ1. The system shall support registering new investors by providing a real-world email, which shall be external to our website. Required information shall include a unique login ID and a password that conforms to the guidelines, as well as investors first and last name and other demographic information. Upon successful registration, the system shall set up an account with a zero balance for the investor. REQ2. The system shall support placing Market Orders specified by the action (buy/sell), the stock to trade, and the number of shares. The current indicative (ask/bid) price shall be shown and updated in real time. The system shall also allow specifying the upper/lower bounds of the

Ivan Marsic

Rutgers University

134

stock price beyond which the investor does not wish the transaction executed. If the action is to buy, the system shall check that the investor has sufficient funds in his/her account. When the market order matches the current market price, the system shall execute the transaction instantly. It shall then issue a confirmation about the outcome of the transaction (known as order ticket), which contains: the unique ticket number, investors name, stock symbol, number of shares, the traded share price, the new portfolio state, and the investors new account balance. We start by listing all the declarative sentences that can be extracted from the requirements. REQ1 yields the following declarative sentences. Keep in mind that these are not necessarily propositions because we still do not know whether they have truth value. Label a b c d e f g h Declarative sentence (not necessarily a proposition!) The investor can register with the system The email address entered by the investor exists in real world The email address entered by the investor is external to our website The login ID entered by the investor is unique The password entered by the investor conforms to the guidelines The investor enters his/her first and last name, and other demographic info Registration is successful Account with zero balance is set up for the investor

Next we need to ascertain their truth value. Recall that the specifications state what is true about the system at the time it is delivered to the customer. The truth value of a must be established by the developer before the system is delivered. The truth values of b, c, d, and e depends on what the investor will enter. Hence, these are propositional functions at investors input. Consider the sentence b. Assuming that email denotes the investors input and B denotes the predicate in b, the propositional function is B(email). Similarly, c can be written as C(email), d as D(id), and e as E(pwd). The system can and should evaluate these functions at runtime, during the investor registration, but the specification refers to the system deployment time, not its runtime. I will assume that the truth of sentence f is hard to ascertain so the system will admit any input values and consider f true. We have the following propositions derived from REQ1: REQ1 represented as a set of propositions a ( email)( id)( pwd) [B(email) C(email) D(id) E(pwd) g] f gh The reader should be reminded that conditional statements in logic are different from if-then constructions in programming languages. Hence, g h does not describe a cause-effect sequence of instructions such as: when registration is successful, do set up a zero-balance account. Rather, this simply states that when g is true, h must be true as well. The system correctly implements REQ1 for an assignment of truth values that makes all four propositions true. Note that it would be wrong to simply write (b c d e) g instead of the second proposition above, for this does not correctly reflect the reality of user choice at entering the input parameters. Extracting declarative sentences from REQ2 is a bit more involved than for REQ1. The two most complex aspects of REQ2 seem to be about ensuring the sufficiency of funds for the stock purchase and executing the order only if the current price is within the bounds (in case the trader specified the upper/lower bounds). Let us assume that the ticker symbol selected by the trader is denoted by SYM and its current ask price at the exchange is IP (for indicative price). Notice that unlike the email and password in REQ1, here we can force the user to select a valid ticker symbol by displaying only acceptable options. The number of shares (volume) for the trade specified by the investor is denoted as

Chapter 3

Modeling and System Specification

135

VOL. In case the investor specifies the upper/lower bounds, let their values be denoted as UB and LB, respectively. Lastly, the investors current account balance is denoted as BAL. Here is a partial list of propositions needed to state these two constraints: Label Propositions (partial list) m The action specified by the investor is buy n The investor specified the upper bound of the buy price o The investor specified the lower bound of the sell price The above table contains propositions because their truth value can be established independent of the users choice. For example, the developer should allow only two choices for trading actions, buy or sell, so m means that the investor selected sell. In case the investor specifies the upper/lower bounds, the system will execute the transaction only if [n m (IP UB)] [o m (LB IP)]. To verify that the investors account balance is sufficient for the current trade, the system needs to check that [n (VOL IP BAL)] [n (VOL UB BAL)]. The additional declarative sentences extracted from REQ2 are: Label Propositions (they complete the above list) p The investor requests to place a market order q The investor is shown a blank ticket where the trade can be specified (action, symbol, etc.) r The most recently retrieved indicative price is shown in the currently open order ticket s The symbol SYM specified by the investor is a valid ticker symbol t The current indicative price that is obtained from the exchange u The system executes the trade v The system calculates the players account new balance w The system issues a confirmation about the outcome of the transaction x The system archives the transaction We have the following propositions derived from REQ2: REQ2 represented as a set of propositions pqr s y = v {(n o) [(o p o q) ( IP)(LB IP UB)]} z = m {[n (VOL IP BAL)] [n (VOL UB BAL)]} yzu uvwx Again, all of the above propositions must evaluate to true for the system to correctly implement REQ2. Unlike REQ1, we have managed to restrict the user choice and simplify the representation of REQ2. It is true that by doing this we went beyond mere problem statement and imposed some choices on the problem solution, which is generally not a good idea. But in this case I believe these are very simple and straightforward choices. It requires the developers judgment and experience to decide when simplification goes too far into restricting the solution options, but sometimes the pursuit of purity only brings needless extra work.

System specifications should be consistent, which means that they should not contain conflicting requirements. In other words, if the requirements are represented as a set of propositions, there should be an assignment of truth values to the propositional variables that makes all requirements propositions true. Example

Ivan Marsic

Rutgers University

136

lock

unlock

unlock

Closed

Open

lock

Figure 3-9: State transition diagram for a door lock.

In Section 3.2.3 we will see how logic plays role in the part of the UML standard called Object Constraint Language (OCL). Another notation based on Boolean logic is TLA+, described in Section 3.2.4.

Finite State Machines

The behavior of complex objects and systems depends not only on their immediate input, but also on the past history of inputs. This memory property, represented as a state, allows such systems to change their actions with time. A simple but important formal notation for describing such systems is called finite state machines (FSMs). FSMs are used extensively in computer science and data networking, and the UML standard extends the FSMs into UML state machine diagrams (Section 3.2.2). There are various ways to represent a finite state machine. One way is to make a table showing how each input affects the state the machine is in. Here is the state table for the door lock used in our case-study example Present state Armed Disarmed lock Armed Armed Input unlock Disarmed Disarmed Here, the entries in the body of the table show the next state the machine enters, depending on the present state (column) and input (row). We can also represent our machine graphically, using a transition diagram, which is a directed graph with labeled edges. In this diagram, each state is represented by a circle. Arrows are labeled with the input for each transition. An example is shown in Figure 3-9. Here the states Disarmed and Armed are shown as circles, and labeled arrows indicate the effect of each input when the machine is in each state. A finite state machine is formally defined to consist of a finite set of states S, a finite set of inputs I, and a transition function with S I as its domain and S as its codomain (or range) such that if s S and i I, the f(s, i) is the state the machine moves to when it is in state s and is given input i. Function f can be a partial function, meaning that it can be undefined for some values of its domain. In certain applications, we may also specify an initial state s0 and a set of final (or accepting) states S S, which are the states we would like the machine to end in. Final states are depicted in state diagrams by using double concentric circles. An example is shown in Figure 3-10, where M =

Chapter 3

Modeling and System Specification

lock unlock / beep unlock

137

(a)

Closed

Open

lock / beep

lock

unlock [key Valid-keys] / beep

unlock

(b)

Closed

Open

lock / beep

Figure 3-11: State transition diagram from Figure 3-9, modified to include output labels (a) and guard labels (b). maxNumOfTrials is the final state: the machine will halt in this state and needs to be restarted externally.

A string is a finite sequence of inputs. Given a string i1i2 in and the initial state s0, the machine successively computes s1 = f(s0, i1), then s2 = f(s1, i2), and so on, finally ending up with state sn. For the example in Figure 3-10, the input string iiv transitions the FSM through the states s0s1s2s0. If sn S, i.e., it is an accepting state, then we say that the string is accepted; otherwise it is rejected. It is easy to see that in Figure 3-10, the input string of M is (denoted as iM) will be accepted. We say that this machine recognizes this string and, in this sense, it recognizes the attempted intrusion. A slightly more complex machine is an FSM that yields output when it transitions to the next state. Suppose that, for example, the door lock in Figure 3-9 also produces an audible signal to let the user know that it is armed or disarmed. The modified diagram is shown in Figure 3-11(a). We use a slash symbol to separate the input and the output labels on each transition arrow. (Notice that here we choose to produce no outputs when the machine receives duplicate inputs.) We define a finite state machine with output to consist of a finite set of states S, a finite set of inputs I, a finite set of outputs O, along with a function f : S I S that assigns to each (state, input) pair a new state and another function g : S I O that assigns to each (state, input) pair an output.
Start v i i v = (input-key Valid-keys) i = (input-key Valid-keys) M = maxNumOfTrials

0 v

Figure 3-10: State transition diagram for the counter of unsuccessful lock-opening attempts.

Ivan Marsic

Rutgers University

138

trade IPO planned initial-listing Traded

bankruptcy, acquisition, merger, Delisted

IPO = initial public offering

Figure 3-12: UML state machine diagram showing the states and transitions of a stock.

We can enrich the original FSM model by adding new features. Figure 3-11(b) shows how we can add guards to transitions. The full notation for transition descriptions is then input[guard]/output, where each element is optional. A guard is a Boolean proposition that permits or blocks the transition. When a guard is present, the transition takes place if the guard evaluates to true, but the transition is blocked if the guard is false. Section 3.2.2 describes how UML adds other features to extend the FSM model into UML state machine diagrams.

3.2.2

UML State Machine Diagrams

One of the key weaknesses of the original finite-state-machines model (described in the preceding section) in the context of system and software specification is the lack of modularization mechanisms. When considering the definitions of states and state variables in Section 3.1.2, FSMs are suitable for representing individual simple states (or microstates). UML state machine diagrams provide a standardized diagrammatic notation for state machines and also incorporate extensions, such as macrostates and concurrent behaviors.

Basic Notation
In every state machine diagram, there must be exactly one default initial state, which we designate by writing an unlabeled transition to this state from a special icon, shown as a filled circle. An example is shown in Figure 3-12. Sometimes we also need to designate a stop state. In most cases, a state machine associated with an object or the system as a whole never reaches a stop statethe state machine just vanishes when the object it represents is destroyed. We designate a stop state by drawing an unlabeled state transition from this state to a special icon, shown as a filled circle inside a slightly larger hollow circle.14 Initial and final states are called pseudostates. Transitions between pairs of states are shown by directed arrows. Moving between states is referred to as firing the transition. A state may transition to itself, and it is common to have many different state transitions from the same state. All transitions must be unique, meaning that there will never be any circumstances that would trigger more than one transition from the same state. There are various ways to control the firing of a transition. A transition with no annotation is referred to as a completion transition. This simply means that when the object completes the execution of an activity in the source state, the transition automatically fires, and the target state is entered.
14

The Delisted state in Figure 3-12 is the stop state with respect to the given exchange. Although investors can no longer trade shares of the stock on that exchange, it may be traded on some other markets

Chapter 3

Modeling and System Specification

139

archive Pending submit InPreparation do: check_price+supply [buy] check_price+demand [sell] matched Executed Archived

view

data Entry

cancel, reject trade Cancelled

Figure 3-13: Example of state activities for a trading order. Compare with Figure 3-6.

In other cases, certain events have to occur for the transition to fire. Such events are annotated on the transition. (Events were discussed is Section 3.1.3.) In Figure 3-12, one may argue that bankruptcy or acquisition phenomena should be considered states rather than events, because company stays in bankruptcy for much longer than an instant of time. The correct answer is relative to the observer. Our trader would not care how long the company will be in bankruptcy the only thing that matters is that its stock is not tradable anymore starting with the moment the bankruptcy becomes effective. We have already seen for FSMs that a guard condition may be specified to control the transition. These conditions act as guards so that when an event occurs, the condition will either allow the transition (if the condition is true) or disallow the transition (if the condition is false).

State Activities: Entry, Do, and Exit Activities

I already mentioned that states can be passive or active. In particular, an activity may be specified to be carried out at certain points in time with respect to a state: Perform an activity upon entry of the state Do an activity while in the state Perform an activity upon exit of the state

An example is shown in Figure 3-13.

Composite States and Nested States

UML state diagrams define superstates (or macrostates). A superstate is a complex state that is further refined by decomposition into a finite state machine. A superstate can also be obtained by aggregation of elementary states, as already seen in Section 3.1.2.

Ivan Marsic

Rutgers University

140

Traded trade initiallisting trade trade Buy trade

nested state

trade trade Hold trade Sell

bankruptcy, acquisition, merger, Delisted

IPO planned

composite state

trade

Figure 3-14: Example of composite and nested states for a stock. Compare with Figure 3-12.

Suppose now that we wish to extend the diagram in Figure 3-12 to show the states Buy, Sell, and Hold, which we defined in Example 3.2. These states are a refinement of the Traded state within which they are nested, as shown in Figure 3-14. This nesting is depicted with a surrounding boundary known as a region and the enclosing boundary is called a composite state. Given the composite state Traded with its three substates, the semantics of nesting implies an exclusive OR (XOR) relationship. If the stock is in the Traded state (the composite state), it must also be in exactly one of the three substates: Buy, Hold, or Sell. Nesting may be to any depth, and thus substates may be composite states to other lower-level substates. For simplicity in drawing state transition diagrams with depth, we may zoom in or zoom out relative to a particular state. Zooming out conceals substates, as in Figure 3-12, and zooming in reveals substates, as in Figure 3-14. Zoomed out representation may improve comprehensibility of a complex state machine diagram.

Concurrency
Figure 3-15

Applications
State machine diagrams are typically used to describe the behavior of individual objects. However, they can also be used to describe the behavior of any abstractions that the developer is currently considering. We may also provide state machine diagrams for the entire system under consideration. During the analysis phase of the development lifecycle (described in Section 2.4), we are considering the event-ordered behavior of the system as a whole; hence, we may use state machine diagrams to represent the behavior of the system. During the design phase (described in Section 2.5), we may use state machine diagrams to capture dynamic behavior of individual classes or of collaborations of classes.

Chapter 3

Modeling and System Specification

141

Figure 3-15: Example of concurrency in states.

In Section 3.3 we will use state machine diagrams to describe problem domains when trying to understand and decompose complex problems into basic problems.

3.2.3

UML Object Constraint Language (OCL)

I can speak French but I cannot understand it. Mark Twain

The UML standard defines Object Constraint Language (OCL) based on Boolean logic. Instead of using mathematical symbols for operators (Table 3-1), OCL uses only ASCII characters which makes it easier for typing and computer processing. It also makes OCL a bit wordy in places. OCL is not a standalone language, but an integral part of the UML. An OCL expression needs to be placed within the context of a UML model. In UML diagrams, OCL is primarily used to write constraints in class diagrams and guard conditions in state and activity diagrams. OCL expressions, known as constraints, are added to state facts about elements of UML diagrams. Any implementation derived from such a design model must ensure each of the constraints always remains true. We should keep in mind that for software classes there is no notion of a computation to specify in the sense of having well-defined start and end points. A class is not a program or subroutine. Rather, any of objects operations can be invoked at arbitrary times with no specific order. And the state of the object can be an important factor in its behavior, rather than just input-output relations for the operation. Depending on its state, the object may act differently for the same operation. To specify the effect of an operation on objects state, we need to be able to describe the present state of the object which resulted from any previous sequence of operations invoked on it. Because objects state is captured in its attributes and associations with other objects, OCL constraints usually relate to these properties of objects.

OCL Syntax
OCLs syntax is similar to object-oriented languages such as C++ or Java. OCL expressions consist of model elements, constraints, and operators. Model elements include class attributes, operations, and associations. However, unlike programming languages OCL is a pure specification language, meaning that an OCL expression is guaranteed to be without side effects. When an OCL expression is evaluated, it simply returns a value. The state of the system will

Ivan Marsic

Rutgers University

142

Table 3-2: Basic predefined OCL types and operations on them. Type Boolean Integer Real String Values true, false 1, 48, 3, 84967, 0.5, 3.14159265, 1.e+5 'With more exploration comes more text.' Operations and, or, xor, not, implies, if-then-else *, +, , /, abs() *, +, , /, floor() concat(), size(), substring()
(c) Indirectly related class
Class_A * assocBA

(a) Local attribute

Class_A attribute1 attribute2

(b) Directly related class

Class_A * assocBA

assocAB

assocAB

Class_B

Class_B * assocCB

assocBC

Class_C

Figure 3-16: Three basic types of navigation.

never change because of the evaluation of an OCL expression, even though an OCL expression can be used to specify a state change, such as in a post-condition specification. OCL has four built-in types: Boolean, Integer, Real, and String. Table 3-2 shows example values and some examples of the operations on the predefined types. These predefined value types are independent of any object model and are part of the definition of OCL. When writing an OCL contract, the first step is to decide the context, which is the class for which the OCL expression is applicable. Within the given class context, the keyword self refers to all instances of the class. Other model elements can be obtained by navigating using the dot notation from the self object. Consider the example of the class diagram in Figure 2-19. To access the attribute numOfTrials_ of the class Controller, we write
self.numOfTrials_

Due to encapsulation, object attributes frequently must be accessed via accessor methods. Hence, we may need to write self.getNumOfTrials(). Starting from a given context, we can navigate associations on the class diagram to refer to other model elements and their properties. The three basic types of navigation are illustrated in Figure 3-16. In the context of Class_A, to access its local attribute, we write self.attribute2. Similarly, to access instances of a directly associated class we use the name of the opposite association-end in the class diagram. So to access the set of instances of Class_B in Figure 3-16 we write self.assocAB. Lastly, to access instances of an indirectly associated class Class_C, we write self.assocAB.assocBC. We already know from UML class diagrams that object associations may be individual objects (association multiplicity equals 1) or collections (association multiplicity > 1). Navigating a one-

Chapter 3

Modeling and System Specification

143

to-one association yields directly an object. Figure 2-19 shows a single LockCtrl (assuming that a single lock is controlled by the system). Assuming that this association is named lockCtrl_ as in Listing 2.2, the navigation self.lockCtrl_ yields the single object lockCtrl_ : LockCtrl. However, if the Controller were associated with multiple locks, e.g., on front and backyard doors, then this navigation would yield a collection of two LockCtrl objects. OCL specifies three types of collections: OCL sets are used to collect the results of navigating immediate associations with one-tomany multiplicity. OCL sequences are used when navigating immediate ordered associations. OCL bags are used to accumulate the objects when navigating indirectly related objects. In this case, the same object can show up multiple times in the collection because it was accessed via different navigation paths.

Notice that in the example in Figure 3-16(c), the expression self.assocAB.assocBC evaluates to the set of all instances of class Class_C objects associated with all instances of class Class_B objects that, in turn, are associated with class Class_A objects. To distinguish between attributes in classes from collections, OCL uses the dot notation for accessing attributes and the arrow operator -> for accessing collections. To access a property of a collection, we write the collections name, followed by an arrow ->, and followed by the name of the property. OCL provides many predefined operations for accessing collections, some of which are shown in Table 3-3. Constants are unchanging (non-mutable) values of one of the predefined OCL types (Table 3-2). Operators combine model elements and constants to form an expression.

Ivan Marsic

Rutgers University

144

Table 3-3: Summary of OCL operations for accessing collections. OCL Notation Meaning EXAMPLE OPERATIONS ON ALL OCL COLLECTIONS c->size() Returns the number of elements in the collection c. c->isEmpty() Returns true if c has no elements, false otherwise. c1->includesAll(c2) Returns true if every element of c2 is found in c1. c1->excludesAll(c2) Returns true if no element of c2 is found in c1. c->forAll(var | expr) Returns true if the Boolean expression expr true for all elements in c. As an element is being evaluated, it is bound to the variable var, which can be used in expr. This implements universal quantification . c->forAll(var1, var2 Same as above, except that expr is evaluated for every | expr) possible pair of elements from c, including the cases where the pair consists of the same element. c->exists(var | expr) Returns true if there exists at least one element in c for which expr is true. This implements existential quantification . c->isUnique(var | Returns true if expr evaluates to a different value when expr) applied to every element of c. c->select(expr) Returns a collection that contains only the elements of c for which expr is true. EXAMPLE OPERATIONS SPECIFIC TO OCL SETS s1->intersection(s2) Returns the set of the elements found in s1 and also in s2. s1->union(s2) Returns the set of the elements found either s1 or s2. s->excluding(x) Returns the set s without object x. EXAMPLE OPERATION SPECIFIC TO OCL SEQUENCES seq->first() Returns the object that is the first element in the sequence seq.

OCL Constraints and Contracts

Contracts are constraints on a class that enable class users, implementers, and extenders to share the same assumptions about the class. A contract specifies constraints on the class state that must be valid always or at certain times, such as before or after an operation is invoked. The contract is between the class implementer about the promises of what can be expected and the class user about the obligations that must be met before the class is used. There are three types of constraints in OCL: invariants, preconditions, and postconditions. One important characterization of object states is describing what remains invariant throughout the objects lifetime. This can be described using an invariant predicate. An invariant must always evaluate to true for all instance objects of a class, regardless of what operation is invoked and in what order. An invariant applies to a class attribute. In addition, each operation can be specified by stating a precondition and a postcondition. A precondition is a predicate that is checked before an operation is executed. A precondition

Chapter 3

Modeling and System Specification

145

applies to a specific operation. Preconditions are frequently used to validate input parameters to an operation. A postcondition is a predicate that must be true after an operation is executed. A postcondition also applies to a specific operation. Postconditions are frequently used to describe how the objects state was changed by an operation. We already encountered some preconditions and postconditions in the context of domain models (Section 2.4.3). Subsequently, in Figure 2-19 we assigned the domain attributes to specific classes. One of the constraints for our case study system is that the maximum allowed number of failed attempts at disarming the lock is a positive integer. This constraint must be always true, so we state it as an invariant:
context Controller inv: self.getMaxNumOfTrials() > 0

Here, the first line specifies the context, i.e., the model element to which the constraint applies, as well as the type of the constraint. In this case the inv keyword indicates the invariant constraint type. In most cases, the keyword self can be omitted because the context is clear. Other possible types of constraint are precondition (indicated by the pre keyword) and postcondition (indicated by the post keyword). A precondition for executing the operation enterKey() is that the number of failed attempts is less than the maximum allowed number:
context Controller::enterKey(k : Key) : boolean pre: self.getNumOfTrials() < self.getMaxNumOfTrials()

The postconditions for enterKey()are that (1) a failed attempt is recorded, and (2) if the number of failed attempts reached the maximum allowed number, the system becomes blocked and the alarm bell is sounded. The first postcondition can be restated as: (1) If the provided key is not element of the set of valid keys, then the counter of failed attempts after exiting from enterKey() must be by one greater than its value before entering enterKey(). The above two postconditions (1) and (2) can be expressed in OCL as:
context Controller::enterKey(k : Key) : Boolean -- postcondition (1): post: let allValidKeys : Set = self.checker.validKeys() if allValidKeys.exists(vk | k = vk) then getNumOfTrials() = getNumOfTrials()@pre else getNumOfTrials() = getNumOfTrials()@pre + 1 -- postcondition (2): post: getNumOfTrials() >= getMaxNumOfTrials() implies self.isBlocked() and self.alarmCtrl.isOn()

There are three features of OCL used in stating the first postcondition above that the reader should notice. First, the let expression allows one to define a variable (in this case allValidKeys of the OCL collection type Set) which can be used in the constraint.

Ivan Marsic

Rutgers University

146

Second, the @pre directive indicates the value of an object as it existed prior to the operation. getNumOfTrials()@pre denotes the value returned by Hence, getNumOfTrials()before invoking enterKey(), and getNumOfTrials()denotes the value returned by the same operation after invoking enterKey(). Third, the expressions about getNumOfTrials() in the if-then-else operation are not assignments. Recall that OCL is not a programming language and evaluation of an OCL expression will never change the state of the system. Rather, this just evaluates the equality of the two sides of the expression. The result is a Boolean value true or false.
THE DEPENDENT DELEGATE DILEMMA

The class invariant is a key concept of object-oriented programming, essential for reasoning
about classes and their instances. Unfortunately, the class invariant is, for all but non-trivial examples, not always satisfied. During the execution of the method that client object called on the server object (dependent delegate), the invariant may be temporarily violated. This is considered acceptable because in such an intermediate state the server object is not directly usable by the rest of the worldit is busy executing the method that client calledso it does not matter that its state might be inconsistent. What counts is that the invariant will hold before and after the execution of method calls. However, if during the executing of the servers method the server calls back a method on the client, then the server may catch the client object in an inconsistent state. This is known as the dependent delegate dilemma and is difficult to handle. The interested reader should check [Meyer, 2005] for more details. The OCL standard specifies only contracts. Although not part of the OCL standard, nothing prevents us from specifying program behavior using Boolean logic. [ give example ]

3.2.4

TLA+ Notation

This section presents TLA+ system specification language, defined by Leslie Lamport. The book describing TLA+ can be downloaded from http://lamport.org/. There are many other specification languages, and TLA+ reminds in many ways of Z (pronounced Zed, not Zee) specification language. My reason for choosing TLA+ is that it uses the language of mathematics, specifically the language of Boolean algebra, rather than inventing another formalism. A TLA+ specification is organized in a module, as in the following example, Figure 3-17, which specifies our home access case study system (Section 1.3.1). Observe that TLA+ language reserved words are shown in SMALL CAPS and comments are shown in a highlighted text. A module comprises several sections Declaration of variables, which are primarily the manifestations of the system visible to an outside observer Definition of the behavior: the initial state and all the subsequent (next) states, which combined make the specification

Chapter 3

Modeling and System Specification

MODULE

147

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

validKeys, ValidateKey( _ ) ASSUME validKeys STRING ASSUME key STRING : ValidateKey(key) BOOLEAN VARIABLE status TypeInvariant = status [lock : {disarmed, armed}, bulb : {lit, unlit}]
CONSTANTS

AccessController The set of valid keys. A ValidateKey(k) step checks if k is a valid key.

Init = TypeInvariant status.lock = armed status.bulb = unlit Unlock(key) = ValidateKey(key) status.lock = disarmed status.bulb = lit Lock = status.lock = armed UNCHANGED status.bulb Next = Unlock(key) Lock Spec = Init [Next]status
THEOREM

The initial predicate.

Only if the user enters a valid key, then unlock the lock and turn on the light (if not already lit). Anybody can lock the doors but not to play with the lights. The next-state action. The specification. Type correctness of the specification.

Spec

TypeInvariant

Figure 3-17: TLA+ specification of the cases study system.

The theorems about the specification

The variables could include internal, invisible aspects of the system, but they primarily address the external systems manifestations. In our case-study of the home access controller, the variables of interest describe the state of the lock and the bulb. They are aggregated in a single status record, lines 6 and 7. The separator lines 8 and 20 are a pure decoration and can be omitted. Unlike these, the module start and termination lines, lines 1 and 22, respectively, have semantic meaning and must appear. Lines 2 and 3 declare the constants of the module and lines 4 and 5 list our assumptions about these constants. For example, we assume that the set of valid passwords is a subset of all character strings, symbolized with STRING. Line 5 essentially says that we expect that for any key k, ValidateKey(k) yields a BOOLEAN value. TypeInvariant in line 7 specifies all the possible values that the system variable(s) can assume in a behavior that satisfies the specification. This is a property of a specification, not an assumption. That is why it is stated as a theorem at the end of the specification, line 21. The definition of the initial system state appears in lines 9 and 10. Before defining the next state in line 17, we need to define the functions that could be requested of the system. In this case we focus only on the key functions of disarming and arming the lock,

Ivan Marsic

Rutgers University

148

Disarm and Arm, respectively, and ignore the rest (see all the use cases in Section 2.2). Defining these functions is probably the most important part of a specification. The variable status with an apostrophe symbol represents the state variable in the next step, after an operation takes place.

3.3 Problem Frames

Computers are useless. They can only give you answers. Pablo Picasso Solving a problem simply means representing it so as to make the solution transparent. Herbert Simon, The Sciences of the Artificial

Problem frames were proposed by Michael Jackson [1995; 2001] as a way for systematic describing and understanding the problem as a first step towards the solution. Problem frames decompose the original complex problem into simple, known subproblems. Each frame captures a problem class stylized enough to be solved by a standard method and simple enough to present clearly separated concerns. We have an intuitive feeling that a problem of data acquisition and display is different from a problem of text editing, which in turn is different from writing a compiler that translates source code to machine code. Some problems combine many of these simpler problems. The key idea of problem frames is to identify the categories of simple problems, and to devise a methodology for representing complex problems in terms of simple problems. There are several issues to be solved for successful formulation of a problem frame methodology. First we need to identify the frame categories. One example is the information frame, which represents the class of problems that are primarily about data acquisition and display. We need to define the notation to be used in describing/representing the frames. Then, given a complex problem, we need to determine how to decompose it into a set of problem frames. Each individual frame can then be considered and solved independently of other frames. Finally, we need to determine how to compose the individual solutions into the overall solution for the original problem. We need to determine how individual frames interact with each other and we may need to resolve potential conflicts.

3.3.1

Problem Frame Notation

We can picture the relationship between the computer system to be developed and the real world where the problem resides as in Figure 3-18. The task of software development is to construct the Machine by programming a general-purpose computer. The machine has an interface a consisting of a set of phenomenatypically events and statesshared with the Problem Domain. Example phenomena are keystrokes on a computer keyboard, characters and symbols shown on a computer screen, signals on the lines connecting the computer to an instrument, etc. The purpose of the machine is represented by the Requirement, which specifies that the machine must produce and maintain some relationship among the phenomena of the problem domain. For

Chapter 3

Modeling and System Specification

149

(a)

The Machine

Problem Domain

The Requirement

(b)
The Machine

Domain properties seen by the requirement a b

Problem Domain

The Requirement

Specification

Domain properties seen by the machine

Requirement

a: specification interface phenomena b: requirement interface phenomena

Figure 3-18: (a) The Machine and the Problem Domain. (b) Interfaces between the problem domain, the requirements and the machine.

example, to disarm the lock device when a correct code is presented, or to ensure that the figures printed on a restaurant check correctly reflect the patrons consumption. Phenomena a shared by a problem domain and the machine are called specification phenomena. Conversely, phenomena b articulate the requirements and are called the requirement phenomena. Although a and b may be overlapping, they are generally distinct. The requirement phenomena are the subject matter of the customers requirement, while the specification phenomena describe the interface at which the machine can monitor and control the problem domain. A problem diagram as in Figure 3-18 provides a basis for problem analysis because it shows you what you are concerned with, and what you must describe and reason about in order to analyze the problem completely. The key topics of your descriptions will be: The requirement that states what the machine must do. The requirement is what your customer would like to be true in the problem domain. Its description is optative (it describes the option that the customer has chosen). Sometimes you already have an exact description of the requirement, sometimes not. For example, requirement REQ1 given in Table 2-2 states precisely how users are to register with our system. The domain properties that describe the relevant characteristics of each problem domain. These descriptions are indicative because they describe what is true regardless of the machines behavior. For example, Section 1.3.2 describes the functioning of financial markets, which we must understand to implement a useful system that will provide investment advice. The machine specification. Like the requirement, this is an optative description: it describes the machines desired behavior at its interfaces with the problem domains.

Obviously, the indicative domain properties play a key role: without a clear understanding of how financial markets work we would never be able to develop a useful investment assistant system.

Ivan Marsic

Rutgers University

150

Control Machine

CM!C1 CD!C2

Controlled Domain

C3
C

Required Behavior

Figure 3-19: Problem frame diagram for the required behavior frame.

3.3.2

Problem Decomposition into Frames

Problem analysis relies on a strategy of problem decomposition based on the type of problem domain and the domain properties. The resulting sub-problems are treated independently of other sub-problems, which is the basis of effective separation of concerns. Each sub-problem has its own machine (specification), problem domain(s), and requirement. Each sub-problem is a projection of the full problem, like color separation in printing, where colors are separated independently and then overlaid (superimposed) to form the full picture. Jackson [2001] identifies five primitive problem frames, which serve as basic units of problem decomposition. These are (i) required behavior, (ii) commanded behavior, (iii) information display, (iv) simple workpieces, and (v) transformation. They differ in their requirements, domain characteristics, domain involvement (whether the domain is controlled, active, inert, etc.), and frame concern. Identification and analysis of frame flavors, reflecting a finer classification of domain properties The frame concern is to make the requirement, specification, and domain descriptions and to fit them into a correctness argument for the machine to be built. Frame concerns include: initialization, overrun, reliability, identities, and completeness. The initialization concern is to ensure that a machine is properly synchronized with the real world when it starts. frame variants, in which a domain is usually added to a problem frame

Basic Frame Type 1: Required Behavior

In this scenario, we need to build a machine which controls the behavior of a part of the physical world according to given conditions. Figure 3-19 shows the frame diagram for the required behavior frame. The control machine is the machine (system) to be built. The controlled domain is the part of the world to be controlled. The requirement, giving the condition to be satisfied by the behavior of the controlled domain, is called the required behavior. The controlled domain is a causal domain, as indicated by the C in the bottom right corner of its box. Its interface with the machine consists of two sets of causal phenomena: C1, controlled by the machine, and C2, controlled by the controlled domain. The machine imposes the behavior on the controlled domain by the phenomena C1; the phenomena C2 provide feedback. An example is shown in Figure 3-20 for how a stock-brokers system handles trading orders. Once an order is placed, this is recorded in the brokers machine and from now on the machine monitors the quoted prices to decide when the conditions for executing the order are met. When

Chapter 3

Modeling and System Specification

151

Control Machine Broker Machine

Controlled Domain

Required Behavior

Stock Exchange

b
C

Order handling rules

a: BM! {Execute[i]} [C1] SE! {PriceQuotes, Ack[i]} [C2]

b: SE! {Place[i], Cancel[i], Executed[i], Expired[i]} [C3]

Figure 3-20: Example of a Required Behavior basic frame: handling of trading orders.
ET!E1 WP!Y2
Editing tool Work pieces

Y3
Command effects

US!E3

User B

E3

Figure 3-21: Problem frame diagram for the simple workpieces frame.

the conditions are met, e.g., the price reaches a specified value, the controlled domain (stock exchange) is requested to execute the order. The exchange will execute the order and return an acknowledgement.

Basic Frame Type 2: Commanded Behavior

In this scenario, we need to build a machine which allows an operator to control the behavior of a part of the physical world by issuing commands.

Basic Frame Type 3: Information Display

In this scenario, we need to build a machine which acquires information about a part of the physical world and presents it at a given place in a given form.

Basic Frame Type 4: Simple Workpieces

In this scenario, we need to build a machine which allows a user to create, edit, and store some data representations, such as text or graphics. Figure 3-21 shows the frame diagram for the simple workpieces frame. An example is shown in Figure 3-22.

Basic Frame Type 5: Transformation

In this scenario, we need to build a machine takes an input document and produces an output document according to certain rules, where both input and output documents may be formatted differently.

Ivan Marsic

Rutgers University

152

Workpieces Trading order Command effects Order placing rules

Editing tool Trading machine

Trader B User

a: TM! {Create[i]}

[E1]

b: TR! {PriceQuotes, Place[i]} [Y2]

c: TR! {Place[i], Cancel[i], Executed[i], Expired[i]} [Y3]

Figure 3-22: Example of a Simple Workpieces basic frame: placing a trading order.

Figure 3-23 shows the key idea behind the frame decomposition. Given a problem represented as a complex set of requirements relating to a complex application domain, our goal is to represent the problem using a set of basic problem frames.

3.3.3

Composition of Problem Frames

Real-world problems almost always consist of combinations of simple problem frames. Problem frames help us achieve understanding of simple subproblems and derive solutions (machines) for these problem frames. Once the solution is reached at the local level of specialized frames, the integration (or composition) or specialized understanding is needed to make a coherent whole. There are some standard composite frames, consisting of compositions of two or more simple problem frames.

Chapter 3

Modeling and System Specification

153

Domain 1

The Requirements

Domain 5

(a)

The Machine

Domain 2

Domain 4

Domain 3

e nt uirem Req 1

Requirement 2

qui Re

rem e

nt

Domain 2

Do ma in 4

(b)

ain Dom 1

Do

ma in 3

m re ui eq 4 R

t en

n ai m Do 5

Machine 2

hine 1

Ma ch i n 3 e

e hin ac 4 M

Figure 3-23: The goal of frame decomposition is to represent a complex problem (a) as a set of basic problem frames (b).

3.3.4

Models

Software system may have world representation and this is always idealized. E.g., in our lock system, built-in (as opposed to runtime sensed/acquired) knowledge is: IF valid key entered AND sensing dark THEN turn on the light.

Mac

Ivan Marsic

Rutgers University

154

3.4 Specifying Goals

Correctness is clearly the prime quality. If a system does not do what it is supposed to do, then everything else about it matters little. Bertrand Meyer

The basic idea of goal-oriented requirements engineering is to start with the aggregate goal of the whole system, and to refine it by successive steps into a goal hierarchy. AND-OR refinements Problem frames can be related to goals. Goal-oriented approach distinguishes different kinds of goal, as problem-frames approach distinguishes different problem classes. Given a problem decomposition into basic frames, we can restate this as an AND-refinement of the goal hierarchy: to satisfy the system requirement goal, it is necessary to satisfy each individual subgoal (of each basic frame). When programmed, the program knows its goals implicitly rather than explicitly, so it cannot tell those to another component. This ability to tell its goals to others is important in autonomic computing, as will be seen in Section 9.3. State the goal as follows: given the states A=armed, B=lightOff, C=user positively identified, D=daylight (Goal is the equilibrium state to be reached after a perturbation.) Initial state: AB, goal state: AB. Possible actions: setArmed; 1setDisarmed; setLit; 1setUnlit Preconditions for 1: C; for : D We need to make a plan to achieve AB by applying the permitted actions.

Program goals, see also fuzzy goals for multi-fidelity algorithms, MFAs, [Satyanarayanan & Narayanan, 2001]. http://www.cs.yale.edu/homes/elkin/ (Michael Elkin) The survey Distributed approximation, by Michael Elkin. ACM SIGACT News, vol. 36, no. 1, (Whole Number 134), March 2005. http://theory.lcs.mit.edu/~rajsbaum/sigactNewsDC.html The purpose of this formal representation is not to automatically build a program; rather, it is to be able to establish that a program meets its specification.

Chapter 3

Modeling and System Specification

155

3.5 Summary and Bibliographical Notes

This chapter presents

I have seen many software-development luminaries gripe about software quality (see [Jackson, 2001], Ch.12 Microsoft Word example). I feel that the situation is much more complex than ensuring quality. Software appeal depends on what it does (functionality), how good it is (quality), and what it costs (economy). Different people put different weights on each of these, but in the end all three matter. Microsoft figured that the functionality they deliver is beyond the reach of smeller software vendors who cannot produce it at a competitive price, so they emphasized functionality. It paid off. It appears that the market has been more interested in lowcost, feature-laden products than reliability (for the mass market kind of products). It worked in the market, thus far, which is the ultimate test. Whether this strategy will continue to work, we do not know. But the tradeoff between quality / functionality / economy will always be present. Also see the virtues if the good enough principle extolled here: S. Baker, Why good enough is good enough: Imperfect technology greases innovationand the whole marketplace, Business Week, no. 4048, p. 48, September 3, 2007. Online at: http://www.businessweek.com/magazine/content/07_36/b4048048.htm

Comment
Formal specifications have had lack of success, usually blamed on non-specialists finding such specifications difficult to understand, see e.g., [Sommerville, 2004, p. 116; Larman, 2005, p. 65]. The usual rationale given for avoiding rigorous, mathematically driven program development is the time-to-market argumentrigor takes too much time and that cannot be afforded in todays world. We are also told that such things make sense for developing safety-critical applications, such as hospital systems, or airplane controls, but not for everyday use. Thanks to this philosophy, we can all enjoy Internet viruses, worms, spam, spyware, and many other inventions that are thriving on lousy programs. The problem, software ends up being used for purposes that it was not intended for. Many of-theshelf software products end up being used in mission-critical operations, regardless of the fact that they lack robustness necessary to support such operations. It is worth noticing that often we dont wear what we think is coolwe often wear what the trend setters in our social circle, or society in general, wear [Gladwell, 2000]. But, as Petroski [1992], echoing Raymond Loewy, observes, it has to be MAYAmost advanced, yet acceptable. So, if hackers let the word out that some technique is cool, it shall become cool for the masses of programmers.

Bibliographical Notes
Much of this chapter is directly inspired by the work of Michael Jackson [1995; 2001]. I have tried to retell it in a different way and relate it to other developments in software engineering. I

Ivan Marsic

Rutgers University

156

hope I have not distorted his message in the process. In any case, the reader would do well by consulting the original sources [Jackson, 1995; 2001]. This chapter requires some background in discrete mathematics. I tried to provide a brief overview, but the reader may need to check a more comprehensive source. [Rosen, 2007] is an excellent introduction to discrete mathematics and includes very nice pieces on logic and finite state machines. [Guttenplan, 1986] [Woodcock & Loomes, 1988] J. P. Bowen and M. G. Hinchey, Ten commandments of formal methods ten years later, IEEE Computer, vol. 39, no. 1, pp. 40-48, January 2006.

The original sources for problem frames are [Jackson, 1995; 2001]. The reader can also find a great deal of useful information online at: http://www.ferg.org/pfa/ .

Problem 3.7: Elevator Control given below is based on the classical elevator problem, which first appeared in Donald Knuths book, The Art of Computer Programming: Vol. 1, Fundamental Algorithms. It is based on the single elevator in the mathematics building at the California Institute of Technology, where Knuth was a graduate student. Knuth used the elevator problem to illustrate co-routines in an imaginary computing machine, called MIX. A detailed discussion of software engineering issues in elevator control is available in [Jackson, 2001].

Problems
Problem 3.1

Problem 3.2
Consider a system consisting of a button and two light bulbs, as shown in the figure. Assume that the system starts from the initial state where both bulbs are turned off. When the button is pressed the first time, one of the bulbs will be lit and the other remains unlit. When the button is pressed the second time, the bulb which is currently lit will be turned off and the other bulb will be lit. When the button is pressed the third time, both bulbs will be lit. When the button is pressed the fourth time, both bulbs will be turned off. For the subsequent button presses, the cycle is repeated.

Chapter 3

Modeling and System Specification

157

Name and describe all the states and events in this system. Draw the UML state diagram and be careful to use the correct symbols.

Problem 3.3
Consider the auto-locking feature of the case study of the home access-control system. In Section 0 this feature is described via use cases (a timer is started when the doors are unlocked and if it counts down to zero, the doors will be automatically locked). Suppose now that you wish to represent the auto-locking subsystem using UML state diagrams. The first step is to identify the states and events relevant for the auto-locking subsystem. Do the following: (a) Name and describe the states that adequately represent the auto-locking subsystem. (b) Name and describe the events that cause the auto-locking subsystem to transition between the states. (Note: You do not need to use UML notation to draw a state diagram, just focus on identifying the states and events.)

Problem 3.4
Suppose that in the virtual mitosis lab (described at the book website, given in Preface), you are to develop a finite state machine to control the mechanics of the mitosis process. Write down the state transition table and show the state diagram. See also Problem 2.12.

Problem 3.5

Problem 3.6

Problem 3.7: Elevator Control

Consider developing a software system to control an elevator in a building. Assume that there will be a button at each floor to summon the elevator, and a set of buttons inside the elevator carone button per floor to direct the elevator to the corresponding floor. Pressing a button will be detected as a pulse (i.e., it does not matter if the user keeps holding the button pressed). When pressed, the button is illuminated. At each floor, there will be a floor sensor that is on when the elevator car is within 10 cm of the rest position at the floor.

Ivan Marsic

Rutgers University

158

There will be an information panel above the elevator doors on each floor, to show waiting people where the elevator car is at any time, so that they will know how long they can expect to wait until it arrives. The information panels will have two lamps representing each floor (see the figure below). A square lamp indicates that the car is at the corresponding floor, and a round lamp indicates that there is a request outstanding for the elevator to visit the corresponding floor. In addition, there will be two arrow-shaped lamps to indicate the current direction of travel. For example, in the figure below, the panel indicates that the elevator car is currently on the fifth floor, going up, and there are outstanding requests to visit the lobby, third, fourth, and sixth floor. After the elevator visits a requested floor, the corresponding lamp on all information panels should be turned off. Also, the button that summoned the elevator to the floor should be turned off. Let us assume that the outstanding requests are served so that the elevator will first visit all the requested floors in the direction to which it went first after the idle state. After this, it will serve the requests in the opposite direction, if any. When the elevator has no requests, it remains at its current floor with its doors closed.
L 2 3
4 5 6 7
Up

Requests outstanding to visit the floors L 2 3 4 5 6 Up 7 Floor where the elevator currently is Direction of travel

Down

Down

Button to summon the elevator to this floor

Suppose that you already have designed UML interaction and class diagrams. Your system will execute in a single thread, and your design includes the following classes:
ElevatorMain: This class runs an infinite loop. During each iteration it checks the physical buttons whether any has been pressed and reads the statuses of all the floor sensors. If a button has been pressed or the elevator car arrived/departed a floor, it calls the appropriate classes to do their work, and then starts a new iteration. CarControl: This class controls the movement of the elevator car. This class has the attribute requests that lists the outstanding requests for the elevator to visit the corresponding floors. It also has three operations: addRequest(floorNum : int) adds a request to visit the floor floorNum; stopAt(floorNum : int) requests the object to stop the car at the floor floorNum. This operation calls DoorControl.operateDoors() to open the doors, let the passengers in or out, and close the doors. When operateDoors() returns, the CarControl object takes this as a signal that it is safe to start moving the car from the current floor (in case there are no pending requests, the car remains at the current floor).

Chapter 3

Modeling and System Specification

159

InformationPanel: This class controls the display of information on the elevator information panel. It also has the attribute requests and these operations: arrivedAt(floorNum : int) informs the software object that the car has arrived at the floor floorNum. departed() which informs the object that the car has departed from the current floor. OutsideButton: This class represents the buttons located outside the elevator on each floor that serve to summon the elevator. The associated physical button should be illuminated when pressed and turned off after the car visits the floor. This class has the attribute illuminated that indicates whether the button was pressed. It also has two operations: illuminate() requests the object to illuminate the associated physical button (because it was pressed); turnOff()requests the object to turn off the associated physical button (because the elevator car has arrived at this floor). InsideButton: This class represents the buttons located inside the elevator car that serve to direct the elevator to the corresponding floor. The associated physical button should be illuminated when pressed and turned off after the car visits the floor. It has the same attributes and operations as the class OutsideButton. DoorControl: This class controls opening and closing of the elevator doors on each floor. This class has the Boolean attribute doorsOpen that is set true when the associated doors are open and false otherwise. It also has the operation: operateDoors() : void tells the software object when to open the doors. This operation sets a timer for a given amount of time to let the passengers in or out; after the timer expires, the operation closes the doors automatically and returns.

Notice that some classes may have multiple instances (software objects), because there are multiple corresponding physical objects. For example, there is an information panel, outside button, and doors at each floor. Notice also that we do not have a special class to represents a floor sensor that senses when the elevator car is in or near the rest position at the floor. The reason for this choice is that this system is single-threaded and the ElevatorMain object will notify the interested objects about the floor sensor status, so there is no reason to keep this information in a class dedicated solely for this purpose. Draw the interaction and class diagrams corresponding to the design described above.

Problem 3.8
Consider the class diagram for an online auction website given in Figure 2-28, and the system as described in Problem 2.16 for which the solution is given on the back of this text. Suppose that you want to specify a contract for the operation closeAuction(itemName : String) of the class Controller. To close auction on an item means that no new bids will be accepted; the item is offered to the current highest bidder. If this bidder fails to pay within the specified time interval, the auction may be reopened. You want to specify the preconditions that the auction for the item itemName is currently open and the item is not reserved. The postconditions should state that the auction is closed, and the

Ivan Marsic

Rutgers University

160

item is reserved to the name of the highest bidder, given that there was at least one bidder. Write this contract as statements in OCL. You may add more classes, attributes, or operations, if you feel that this is necessary to solve the problem, provided that you justify your modification.

Problem 3.9

Software Measurement and Estimation

Chapter 4

Contents
Measurement is a process by which numbers or symbols are assigned to properties of objects. To have meaningful assignment of numbers, it must be governed by rules or theory (model). There are many properties of software that can be measured. Similarities can be drawn with physical objects: we can measure height, width, weight, chemical composition, etc., properties of physical objects. The numbers obtained through such measurement have little value by themselves their key value is relative to something we want to do with those objects. For example, we may want to know weight so we can decide what it takes to lift an object. Or, knowing physical dimensions helps us decide whether the object will fit into a certain volume. Similarly, software measurement is usually done with purpose. A common purpose is for management decision making. For example, the project manager would like to be able to estimate the development cost or the time it will take to develop and deliver the software product. Similar to how knowing the object weight helps us to decide what it takes to lift it, the hope is that by measuring certain software properties we will be able to estimate the necessary development effort. Uses of software measurements: Estimation of cost and effort Feedback to guide design and implementation
4.1 Fundamentals of Measurement Theory
4.1.1 Measurement Theory 4.1.2 4.1.3

4.2 What to Measure?

4.2.1 Cyclomatic Complexity 4.2.2 Use Case Points 4.2.3 4.2.4

4.3 Measuring Module Cohesion

4.3.1 Internal Cohesion or Syntactic Cohesion 4.3.2 Semantic Cohesion 4.3.3 4.3.4 4.2.3

4.4 Psychological Complexity

4.4.1 Algorithmic Information Content 4.4.2 4.4.3 4.4.4

4.5
4.5.1 4.5.2 4.5.3 4.5.4

4.6 Summary and Bibliographical Notes Problems

Obviously, once a software product is already completed, we know how much effort it took to complete it. The invested effort is directly known, without the need for inferring it indirectly via some other properties of the software. However, that is too late for management decisions. Management decisions require knowing (or estimating) effort prior to project commencement, or at least early enough in the process, so we can meaningfully negotiate the budget and delivery terms with the customer. Therefore, it is important to understand correctly what measurement is about:

161

Ivan Marsic

Rutgers University

162

Measured property

[ model for estimation ]

Estimated property

(e.g., number of functional features)

(e.g., development effort required)

Notice also that we are trying to infer properties of one entity from properties of another entity: the entity the properties of which are measured is software and the entity the properties of which are estimated is development process. The estimation model is usually based on empirical evidence; that is, it is derived based on observations of past projects. For past projects, both software and process characteristics are known. From this, we can try to calculate the correlation of, say, the number of functional features to, say, the development effort required. If correlation is high across a range of values, we can infer that the number of functional features is a good predictor of the development effort required. Unfortunately, we know that correlation does not equal causation. A causal model, which not only establishes relationship, but also explains why, would be better, if possible to develop. Feedback to the developer is based on the knowledge of good ranges for software modules and systems: if the measured attributes are outside of good ranges, the module needs to be redesigned. It has been reported based on many observations that maintenance costs run to about 70 % of all lifetime costs of software products. Hence, good design can not only speed up the initial development, but can significantly affect the maintenance costs. Most commonly measured characteristics of software modules and systems are related to its size and complexity. Several software characteristics were mentioned in Section 2.5, such as coupling and cohesion, and it was argued that good designs are characterized by low coupling and high cohesion. In this chapter I will present some techniques for measuring coupling and cohesion and quantifying the quality of software design and implementation. A ubiquitous size measure is the number of lines of code (LOC). Complexity is readily observed as an important characteristic of software products, but it is difficult to operationalize complexity so that it can be measured. Although it is easy to agree that more complex software is more difficult to develop and maintain, it is difficult to operationalize complexity so that it can be measured. The reader may already be familiar with computational complexity measure big O (or big Oh), O(n). O(n) measures software complexity from the machines viewpoint in terms of how the size of the input data affects an algorithms usage of computational resources (usually running time or memory). However, the kind of complexity measure that we need in software engineering should measure complexity form the viewpoint of human developers.

4.1 Fundamentals of Measurement Theory

It is better to be roughly right than precisely wrong. John Maynard Keynes

The Hawthorne effect - an increase in worker productivity produced by the psychological stimulus of being singled out and made to feel important. The Hawthorne effect describes a temporary change to behavior or performance in response to a change in the environmental

Chapter 4

Software Measurement and Estimation

163

conditions. This change is typically an improvement. Others have broadened this definition to mean that peoples behavior and performance change following any new or increased attention. Individual behaviors may be altered because they know they are being studied was demonstrated in a research project (19271932) of the Hawthorne Works plant of the Western Electric Company in Cicero, Illinois. Initial improvement in a process of production caused by the obtrusive observation of that process. The effect was first noticed in the Hawthorne plant of Western Electric. Production increased not as a consequence of actual changes in working conditions introduced by the plant's management but because management demonstrated interest in such improvements (related: selffulfilling hypothesis).

4.1.1

Measurement Theory
2 3 4 5 6
7 8 9 0 1
2 3 4 4
5

Measurement theory is a branch of applied mathematics. The specific theory we use is called the representational theory of measurement. It formalizes our intuitions about the way the world actually works.

Measurement theory allows us to use statistics and probability to understand quantitatively the possible variances, ranges, and types of errors in the data.

Measurement Scale
In measurement theory, we have five types of scales: nominal, ordinal, interval, ratio, and absolute. In nominal scale we can group subjects into different categories. The two key requirements for the categories are jointly exhaustive and mutually exclusive. Mutually exclusive means a subject can be classified into one and only one category. Jointly exhaustive means that all categories together should cover all possible categories of the attribute. If the attribute has more categories than we are interested in, an other category can be introduced to make the categories jointly exhaustive. Provided that categories are jointly exhaustive and mutually exclusive, we have the minimal conditions necessary for the application of statistical analysis. For example, we may want to compare the values of interested attributes such as defect rate, cycle time, and requirements defects across the different categories of software products. Ordinal scale refers to the measurement operations through which the subjects can be compared in order. An ordinal scale is asymmetric in the sense that if A > B is true then B > A is false. It has the transitivity property in that if A > B and B > C, then A > C. Although ordinal scale orders subjects by the magnitude of the measured property, it offers no information about the relative magnitude of the difference between subjects. For example, given the scale bad, good, and excellent, we only know that excellent is better than good, and good is better than bad. However, we cannot compare that the relative differences between the excellent-good and goodbad pairs. A commonly used ordinal scale is an n-point Likert scale, such as the Likert five-point, seven-point, or ten-point scales. For example, a five-point Likert scale for rating books or movies may assign the following values: 1 = Hated It, 2 = Didnt Like It, 3 = Neutral, 4 = Liked It, and 5 = Loved It. We know only that 5 > 4, 4 > 3, 5 > 2, etc., but we cannot say how much

Ivan Marsic

Rutgers University

164

greater is 5 than 4. Nor can we say that the difference between categories 5 and 4 is equal to that between categories 3 and 2. This implies that we cannot use arithmetic operations such as addition, subtraction, multiplication and division. Nonetheless, the assumption of equal distance is often made and the average rating reported (e.g., product rating at Amazon.com). Interval scale indicates the exact differences between measurement points. An interval scale requires a well-defined, fixed unit of measurement that can be agreed on as a common standard and that is repeatable. A good example is a traditional temperature scale (centigrade or Fahrenheit scales). Although the zero point is defined in both scales, it is arbitrary and has no meaning. Thus we can say that the difference between the average temperature in Florida, say 80F, and the average temperature in Alaska, say 20F, is 60F, but we do not say that 80F is four times as hot as 20F. The arithmetic operations of addition and subtraction can be applied to interval scale data. Ratio scale is an interval scale for which an absolute or nonarbitrary zero point can be located. Absolute or true zero means that the zero point represents the absence of the property being measured (e.g., no money, no behavior, none correct). Examples are mass, temperature in degrees Kelvin, length, and time interval. Ratio scale is the highest level of measurement and all arithmetic operations can be applied to it, including division and multiplication. For interval and ratio scales, the measurement can be expressed in both integer and noninteger data. Integer data are usually given in terms of frequency counts (e.g., the number of defects that could be encountered during the testing phase). Absolute scale is independent of the physical properties of any specific substance. In practice, values on an absolute scale are usually if not always obtained by counting. An example is counting entities, such as chairs in a room.

Some Basic Measures

Ratio Proportion Percentage Rate Six Sigma

4.2 What to Measure?

Generally, we can measure 1. Attributes of any representation or description of a problem or a solution. Two main categories of representations are structure vs. behavior. 2. Attributes of the development process or methodology.

Chapter 4

Software Measurement and Estimation

165

Measured aspect: quantity (size) complexity

If the purpose of software measurement is estimation of cost and effort, we would like to measure at an early stage in the software life-cycle. Typically a budget allocation is set at an early phase of a procurement process and a decision on contract price made on these budget constraints and suppliers tender responses. Consequently, the functional decomposition of the planned system needs to be at a high level, but must be of sufficient detail to flush out as many of the implied requirements and hidden complexities as possible, and as early as possible. In the ideal world this would be a full and detailed decomposition of the use cases, but this is impractical during the estimation process, because estimates need to be produced within tight time frames.

4.2.1

Cyclomatic Complexity

Thomas McCabe [1974] devised a measure of cyclomatic complexity, intended to capture the complexity of a programs control flow. A program with no branches is the least complex; a program with a loop is more complex; and a program with two crossed loops is more complex still. Cyclomatic complexity corresponds roughly to an intuitive idea of the number of different paths through the programthe greater the number of different paths through a program, the higher the complexity. McCabes metric is based on graph theory, in which you calculate the cyclomatic number of a graph G, denoted by V(G), by counting the number of linearly independent paths within a program. Cyclomatic complexity is V(G) = e n + 2 where e is the number of edges, n is the number of nodes. Converting a program into a graph is illustrated in Figure 4-1. It follows that cyclomatic complexity is also equal to the number of binary decisions in a program plus 1. If all decisions are not binary, a three-way decision is counted as two binary decisions and an n-way case (select or switch) statement is counted as n 1 binary decisions. The iteration test in a looping statement is counted as one binary decision. (4.1)

Ivan Marsic

Rutgers University

166

CODE
if expression1 then statement2 else statement3 end if statement4

FLOWCHART
T expr1 ? F

GRAPH
n1 n2 n3

(a)

statm2

statm3

statm4 switch expr1 case 1: statement2 case 2: statm3 case 3: statm4 end switch statm5 1 3

n4

expr1 ? 2 statm3

n1 statm4 n2 n3 n4

(b)

statm2

statm5

n5

statm1 do

n1

(c)

statement1 while expr2 end do statement3

expr2 ? F statm3

n2 n3

Figure 4-1: Converting software code into an abstract graph. The cyclomatic complexity is additive. The complexity of several graphs considered as a group is equal to the sum of individual graphs complexities. There are two slightly different formulas for calculating cyclomatic complexity V(G) of a graph G. The original formula by McCabe [1974] is V(G) = e n + 2p (4.2)

where e is the number of edges, n is the number of nodes, and p is the number of connected components of the graph. Alternatively, [Henderson-Sellers & Tegarden, 1994] propose a linearly-independent cyclomatic complexity as VLI(G) = e n + p + 1 (4.3)

Because cyclomatic complexity metric is based on decisions and branches, which is consistent with the logic pattern of design and programming, it appeals to software professionals. But it is not without its drawbacks. Cyclomatic complexity ignores the complexity of sequential statements. Also, it does not distinguish different kinds of control flow complexity, such as loops vs. IF-THEN-ELSE statements or selection statements vs. nested IF-THEN-ELSE statements. Cyclomatic complexity metric was originally designed to indicate a programs testability and understandability. It allows you to also determine the minimum number of unique tests that must be run to execute every executable statement in the program. One can expect programs with higher cyclomatic complexity to be more difficult to test and maintain, due to their higher complexity, and vice versa. To have good testability and maintainability, McCabe recommends that no program module should exceed a cyclomatic complexity of 10.

Chapter 4

Software Measurement and Estimation

167

4.2.2

Use Case Points

Intuitively, projects with many complicated requirements take more effort to design and implement than projects with few simple requirements. In addition, the effort depends not only on inherent difficulty or complexity of the problem, but also on what tools the developers employ and how skilled the developers are. The factors that determine the time to complete a project include: Functional requirements: These are often represented with use cases (Section 2.3). The complexity of use cases, in turn, depends on the number and complexity of the actors and the number of steps (transactions) to execute each use case. Nonfunctional requirements: These describe the systems nonfunctional properties, known as FURPS+ (see Section 2.2.3), such as security, usability, and performance. These are also known as the technical complexity factors. Environmental factors: Various factors such as the experience and knowledge of the development team, and how sophisticated tools they will be using for the development.

An estimation method that took into account the above factors early in a projects life cycle, and produced a reasonable accurate estimate, say within 20% of the actual completion time, would be very helpful for project scheduling, cost, and resource allocation. Because use cases are developed at the earliest or notional stages of system design, they afford opportunities to understand the scope of a project early in the software life-cycle. The Use Case Points (UCP) method provides the ability to estimate the person-hours a software project requires based on its use cases. The UCP method analyzes the use case actors, scenarios, nonfunctional requirements, and environmental factors and abstracts them into an equation. Detailed use case descriptions (Section 2.3.3) must be derived before the UCP method can be applied. The UCP method cannot be applied to sketchy use cases. As discussed in Section 2.3.1, we can apply user story points (described in Section 2.2.2) for project effort estimation at this very early stage. The formula for calculating UCP is composed of three variables: 1. Unadjusted Use Case Points (UUCP), which measures the complexity of the functional requirements 2. The Technical Complexity Factor (TCF), which measures the complexity of the nonfunctional requirements 3. The Environment Complexity Factor (ECF), which assesses the development teams experience and their development environment Each variable is defined and computed separately using weighted values, subjective values, and constraining constants. The subjective values are determined by the development team based on their perception of the projects technical complexity and the teams efficiency. Here is the equation: UCP = UUCP TCF ECF (4.4)

Ivan Marsic

Rutgers University

168

Table 4-1: Actor classification and associated weights. Actor type Description of how to recognize the actor type Simple Average Complex The actor is another system which interacts with our system through a defined application programming interface (API). The actor is a person interacting through a text-based user interface, or another system interacting through a protocol, such as a network communication protocol. The actor is a person interacting via a graphical user interface.

Weight 1 2 3

Unadjusted Use Case Points (UUCPs) are computed as a sum of these two components: 1. The Unadjusted Actor Weight (UAW), based on the combined complexity of all the actors in all the use cases. 2. The Unadjusted Use Case Weight (UUCW), based on the total number of activities (or steps) contained in all the use case scenarios. The computation of these components is described next.

Unadjusted Actor Weight (UAW)

An actor in a use case might be a person, another program, a piece of hardware, etc. The weight for each actor depends on how sophisticated is the interface between the actor and the system. Some actors, such as a user working with a text-based command-line interface, have very simple needs and increase the complexity of a use case only slightly. Other actors, such as a user working with a highly interactive graphical user interface, have a much more significant impact on the effort to develop a use case. To capture these differences, each actor in the system is classified as simple, average, or complex, and is assigned a weight as shown in Table 4-1. This scale for rating actor complexity was devised by expert developers based on their experience. Notice that this is an ordinal scale (Section 4.1.1). You can think of this as a scale for star rating, similar to star ratings of books (Amazon.com), films (IMDb.com), or restaurants (yelp.com). Your task is, using this scale, to assign star ratings to all actors in your system. In our case, we can assign one, two, or three stars to actors, corresponding to Simple, Average, or Complex actors, respectively. Table 4-2 shows my ratings for the actors in the case study of home access control, for which the actors are described in Section 2.3.1. The UAW is calculated by totaling the number of actors in each category, multiplying each total by its specified weighting factor, and then adding the products we obtain:

Chapter 4

Software Measurement and Estimation

169

Table 4-2: Actor classification for the case study of home access control (see Section 2.3). Actor name Description of relevant characteristics Complexity Weight Landlord is interacting with the system via a graphical user Landlord Complex 3 interface (when managing users on the central computer). Tenant is interacting through a text-based user interface (assuming that identification is through a keypad; for Tenant Average 2 biometrics based identification methods Tenant would be a complex actor). LockDevice is another system which interacts with our LockDevice Simple 1 system through a defined API. LightSwitch Same as LockDevice. Simple 1 AlarmBell Same as LockDevice. Simple 1 Database Database is another system interacting through a protocol. Average 2 Timer Same as LockDevice. Simple 1 Police Our system just sends a text notification to Police. Simple 1 UAW(home access) = 5 Simple + 2 Average + 1 Complex = 51 + 22 + 13 = 12

Unadjusted Use Case Weight (UUCW)

The UUCW is derived from the number of use cases in three categories: simple, average, and complex (see Table 4-3). Each use case is categorized based on the number of steps (or, transactions) within its event flow, including both the main success scenario and alternative scenarios (extensions). The number of steps in a scenario affects the estimate. A large number of steps in a use case scenario will bias the UUCW toward complexity and increase the UCPs. A small number of steps will bias the UUCW toward simplicity and decrease the UCPs. Sometimes, a large number of steps can be reduced without affecting the business process. The UUCW is calculated by tallying the number of use cases in each category, multiplying each total by its specified weighting factor, and then adding the products. For example, Table 4-4 computes the UUCW for the sample case study. There is a controversy on how to count alternate scenarios (extensions). Initially, it was suggested to ignore all scenarios except the main success scenario. The current view is that extensions represent a significant amount of work and need to be included in effort estimation. However, it is not agreed upon how to do the inclusion. The problem is that you cannot simply count the number of lines in an extension scenario and add those to the lines in the main success scenario.

Ivan Marsic

Rutgers University

170

Table 4-3: Use case weights based on the number of transactions. Use case category Description of how to recognize the use-case category Simple

Weight

Simple user interface. Up to one participating actor (plus initiating actor). Number of steps for the success scenario: 3. If 5 presently available, its domain model includes 3 concepts. Moderate interface design. Two or more participating actors. Number of steps for the success scenario: 4 to 7. If presently available, its domain model includes between 5 and 10 concepts. Complex user interface or processing. Three or more participating actors. Number of steps for the success scenario: 7. If available, its domain model includes 10 concepts. 10

Average

Complex

15

As seen in UC-5: AuthenticateUser (Section 2.3), each extension starts with a result of a transaction, rather than a new transaction itself. For example, extension 2a (Tenant/Landlord enters an invalid identification key) is the result of the transaction described by step 2 of the main success scenario (Tenant/Landlord supplies an identification key). So, item 2a in the extensions section of UC-5: AuthenticateUser is not counted. The same, of course, is true for 2b, 2c, and 3a. The transaction count for the use case in UC-5: AuthenticateUser is then ten. You may want to count 2b1 and 2b2 only once but that is more effort than is worthwhile, and they may be separate transactions sharing common text in the use case. Another mechanism for measuring use case complexity is counting the concepts obtained by domain modeling (Section 2.4). The concepts can be used in place of transactions once it has been determined which concepts model a specific use case. As indicated in Table 4-3, a simple use case is implemented by 5 or fewer concepts, an average use case by 5 to 10 concepts, and a complex use case by more than 10 concepts. The weights are as before. Each type of use case is then multiplied by the weighting factor, and the products are added up to get the UUCW. The UUCW is calculated by tallying the use cases in each category, multiplying each count by its specified weighting factor (Table 4-3), and then adding the products: UUCW(home access) = 1 Simple + 5 Average + 2 Complex = 15 + 510 + 215 = 85 The UUCP is computed by adding the UAW and the UUCW. Based on the scores in Table 4-2 and Table 4-4, the UUCP for our case study project is UUCP = UAW + UUCW = 12 + 85 = 97. The UUCP gives the unadjusted size of the overall system, unadjusted because it does not account for the nonfunctional requirements (TCFs) and the environmental factors (ECFs).

Chapter 4

Software Measurement and Estimation

171

Table 4-4: Use case classification for the case study of home access control (see Section 2.3). Use case Description Category Weight Simple user interface. 5 steps for the main success Unlock (UC-1) Average 10 scenario. 3 participating actors (LockDevice, LightSwitch, and Timer). Simple user interface. 2+3=5 steps for the all Lock (UC-2) scenarios. 3 participating actors (LockDevice, Average 10 LightSwitch, and Timer). Complex user interface. More than 7 steps for the ManageUsers main success scenario (when counting UC-6 or Complex 15 (UC-3) UC-7). Two participating actors (Tenant, Database). ViewAccessHistory Complex user interface. 8 steps for the main success Complex 15 (UC-4) scenario. 2 participating actors (Database, Landlord). AuthenticateUser Simple user interface. 3+1=4 steps for all scenarios. Average 10 (UC-5) 2 participating actors (AlarmBell, Police). Complex user interface. 6 steps for the main success AddUser (UC-6) scenario (not counting UC-3). Two participating Average 10 actors (Tenant, Database). Complex user interface. 4 steps for the main success RemoveUser scenario (not counting UC-3). One participating actor Average 10 (UC-7) (Database). Simple user interface. 2 steps for the main success Login (UC-8) Simple 5 scenario. No participating actors.

Technical Complexity Factor (TCF)Nonfunctional Requirements

Thirteen standard technical factors were identified to estimate the impact on productivity of the nonfunctional requirements for the project (see Table 4-5). Each factor is weighted according to its relative impact. The development team should assess the perceived complexity of each technical factor from Table 4-5 in the context of their project. Based on the assessment, they assign another star rating, a perceived complexity value between zero and five. The perceived complexity value reflects the teams subjective perception of how much effort will be needed to satisfy a given nonfunctional requirement. For example, if they are developing a distributed system, this will require more skill and time than developing a system that would run on a single computer. A perceived complexity value of 0 means the technical factor is irrelevant for this project, 3 corresponds to average effort, and 5 corresponds to major effort. When in doubt, use 3. Each factors weight (Table 4-5) is multiplied by its perceived complexity factor to produce the calculated factor. The calculated factors are summed to produce the Technical Total Factor. Table 4-6 calculates the technical complexity for the case study. Two constants are used with the Technical Total Factor to produce the TCF. The constants limit the impact the TCF has on the UCP equation (4.4) from a range of 0.6 (when perceived complexities are all zero) to a maximum of 1.3 (when perceived complexities are all five), see Figure 4-2(a).

Ivan Marsic

Rutgers University

172

Table 4-5: Technical complexity factors and their weights. Technical factor Description T1 Distributed system (running on multiple machines) Performance objectives (are response time and throughput T2 performance critical?) T3 End-user efficiency T4 Complex internal processing T5 Reusable design or code Easy to install (are automated conversion and installation T6 included in the system?) Easy to use (including operations such as backup, startup, and T7 recovery) T8 Portable T9 Easy to change (to add new features or modify existing ones) T10 Concurrent use (by multiple users) T11 Special security features Provides direct access for third parties (the system will be used T12 from multiple sites in different organizations) T13 Special user training facilities are required
()

Weight 2 1() 1 1 1 0.5 0.5 2 1 1 1 1 1

Some sources assign 2 as the weight for the performance objectives factor (T2).
(70, 1.3) 1.4 1.2 1 ECF 0.8 0.6 0.4 0.2 0 (32.5, 0.425) (0, 1.4)

1.4 1.2 1 TCF 0.8 0.6 0.4 0.2 0 0 10 20 30 40 50 (0, 0.6)

60

70

80

10

20

30

40

Technical Factor Total

Environmental Factor Total

(a)
Figure 4-2: Scaling constants for technical and environmental factors.

(b)

TCF values less than one reduce the UCP because any positive value multiplied by a positive fraction decreases in magnitude: 100 0.6 = 60 (a reduction of 40%). TCF values greater than one increase the UCP because any positive value multiplied by a positive mixed number increases in magnitude: 100 1.3 = 130 (an increase of 30%). The constants were determined based on interviews with experienced developers. Because the constants limit the TCF from a range of 0.6 to 1.3, the TCF can impact the UCP equation from 40% (0.6) to a maximum of +30% (1.3). The formula to compute the TCF is: TCF = Constant-1 + Constant-2 Technical Factor Total = C1 + C 2 Wi Fi
i =1 13

(4.5)

where,

Chapter 4

Software Measurement and Estimation

173

Table 4-6: Technical complexity factors for the case study of home access (see Section 2.3). Calculated Factor Technical Perceived Description Weight (WeightPerceived factor Complexity Complexity) Distributed, Web-based system, because T1 2 3 23 = 6 of ViewAccessHistory (UC-4) Users expect good performance but T2 1 3 13 = 3 nothing exceptional End-user expects efficiency but there are 1 3 T3 13 = 3 no exceptional demands T4 Internal processing is relatively simple 1 1 11 = 1 T5 No requirement for reusability 1 0 10 = 0 Ease of install is moderately important T6 0.5 3 0.53 = 1.5 (will probably be installed by technician) T7 Ease of use is very important 0.5 5 0.55 = 2.5 No portability concerns beyond a desire T8 2 2 22 = 4 to keep database vendor options open T9 Easy to change minimally required 1 1 11 = 1 T10 Concurrent use is required (Section 5.3) 1 4 14 = 4 T11 Security is a significant concern 1 5 15 = 5 T12 No direct access for third parties 1 0 10 = 0 T13 No unique training needs 1 0 10 = 0 Technical Factor Total: 31 Constant-1 (C1) = 0.6 Constant-2 (C2) = 0.01

Wi = weight of ith technical factor (Table 4-5) Fi = perceived complexity of ith technical factor (Table 4-6)
Formula (4.5) is illustrated in Figure 4-2(a). Given the data in Table 4-6, the TCF = 0.6 + (0.01 31) = 0.91. According to equation (4.4), this results in a reduction of the UCP by 9%.

Environment Complexity Factor (ECF)

The environmental factors (Table 4-7) measure the experience level of the people on the project and the stability of the project. Greater experience will in effect reduce the UCP count, while lower experience will in effect increase the UCP count. The development team determines each factors perceived impact based on their perception the factor has on the projects success. A value of 1 means the factor has a strong, negative impact for the project; 3 is average; and 5 means it has a strong, positive impact. A value of zero has no impact on the projects success. For factors E1-E4, 0 means no experience in the subject, 3 means average, and 5 means expert. For E5, 0 means no motivation for the project, 3 means average, and 5 means high motivation. For E6, 0 means unchanging requirements, 3 means average amount of change expected, and 5 means extremely unstable requirements. For E7, 0 means no part-time technical staff, 3 means on average half of the team is part-time, and 5 means all of the team is

Ivan Marsic

Rutgers University

174

Table 4-7: Environmental complexity factors and their weights. Environmental factor Description E1 Familiar with the development process (e.g., UML-based) E2 Application problem experience E3 Paradigm experience (e.g., object-oriented approach) E4 Lead analyst capability E5 Motivation E6 Stable requirements E7 Part-time staff E8 Difficult programming language

Weight 1.5 0.5 1 0.5 1 2 1 1

part-time. For E8, 0 means an easy-to-use programming language will be used, 3 means the language is of average difficulty, and 5 means a very difficult language is planned for the project. Each factors weight is multiplied by its perceived impact to produce its calculated factor. The calculated factors are summed to produce the Environmental Factor Total. Larger values for the Environment Factor Total will have a greater impact on the UCP equation. Table 4-8 calculates the environmental factors for the case study project (home access control), assuming that the project will be developed by a team of upper-division undergraduate students. To produce the final ECF, two constants are computed with the Environmental Factor Total. Similar to the TCF constants above, these constants were determined based on interviews with expert developers. The constants constrain the impact the ECF has on the UCP equation from 0.425 (part-time workers and difficult programming language = 0, all other values = 5) to 1.4 (perceived impact is all 0). Therefore, the ECF can reduce the UCP by 57.5% and increase the UCP by 40%, see Figure 4-2(b). The ECF has a greater potential impact on the UCP count than the TCF. The formula is:

ECF = Constant-1 + Constant-2 Environmental Factor Total = C1 + C 2 Wi Fi

i =1

(4.6)

where, Constant-1 (C1) = 1.4 Constant-2 (C2) = 0.03

Wi = weight of ith environmental factor (Table 4-7) Fi = perceived impact of ith environmental factor (Table 4-8)
Formula (4.6) is illustrated in Figure 4-2(b). Given the data in Table 4-8, the ECF = 1.4 + (0.0311) = 1.07. For the sample case study, the teams modest software development experience resulted in an average EFT. All four factors E1-E4 scored relatively low. According to equation (4.4), this results in an increase of the UCP by 7%.

Chapter 4

Software Measurement and Estimation

175

Table 4-8: Environmental complexity factors for the case study of home access (Section 2.3). Calculated Factor Environmental Perceived Description Weight (Weight factor Impact Perceived Impact) Beginner familiarity with the UMLE1 1.5 1 1.51 = 1.5 based development Some familiarity with application E2 0.5 2 0.52 = 1 problem Some knowledge of object-oriented 1 2 E3 12 = 2 approach E4 Beginner lead analyst 0.5 1 0.51 = 0.5 Highly motivated, but some team E5 1 4 14 = 4 members occasionally slacking E6 Stable requirements expected 2 5 25 = 5 E7 No part-time staff will be involved 0 1 10 = 0 Programming language of average E8 3 1 13 = 3 difficulty will be used Environmental Factor Total: 11

Calculating the Use Case Points (UCP)

As a reminder, the UCP equation (4.4) is copied here:

UCP = UUCP TCF ECF

From the above calculations, the UCP variables have the following values: UUCP = 97 TCF = 0.91 ECF = 1.07 For the sample case study, the final UCP is the following: UCP = 97 0.91 1.07 = 94.45 or 94 use case points. Note for the sample case study, the combined effect of TCF and ECF was to increase the UUCP by approximately 3 percent (94/97100 100 = +3%). This is a minor adjustment and can be ignored given that many other inputs into the calculation are subjective estimates.

Discussion of the UCP Metric

Notice that the UCP equation (4.4) is not consistent with measurement theory, because the counts are on a ratio scale and the scores for the adjustment factors are on an ordinal scale (see Section 4.1.1). However, such formulas are often used in practice. It is worth noticing that UUCW (Unadjusted Use Case Weight) is calculated simply by adding up the perceived weights of individual use cases (Table 4-3). This assumes that all use cases are completely independent, which usually is not the case. The merit of linear summation of size measures was already discussed in Sections 1.2.5 and 2.2.2.

Ivan Marsic

Rutgers University

176

UCP measures how big the software system will be in terms of functionality. The software size is the same regardless of who is building the system or the conditions under which the system is being built. For example, a project with a UCP of 100 may take longer than one with a UCP of 90, but we do not know by how much. From the discussion in Section 1.2.5, we know that to calculate the time to complete the project using equation (1.2) we need to know the teams velocity. How to factor in the team velocity (productivity) and compute the estimated number of hours will be described later in Section 4.5.

4.3 Measuring Module Cohesion

We already encountered the term cohesion in Chapter 2, where it was argued that each unit of design, whether it is at the modular level or component level, should be focused on a single purpose. This means that it should have very few responsibilities that are logically related. Terms such as intramodular functional relatedness or modular strength have been used to address the notion of design cohesion. Cohesion of a unit of high-level or of a detail-level design can be defined as an attribute that identifies to which degree the elements within that unit belong together or are related to each other.

4.3.1

Internal Cohesion or Syntactic Cohesion

Internal cohesion can best be understood as syntactic cohesion evaluated by examining the code of each individual module. It is thus closely related to the way in which large programs are modularized. Modularization can be accomplished for a variety of reasons and in a variety of ways. A very crude modularization is to require that each module should not exceed certain size, e.g., 50 lines of code. This would arbitrarily quantize the program into blocks of about 50 lines each. Alternatively, we may require that each unit of design has certain prescribed size. For example, a package is required to have certain number of classes, or each class a certain number of attributes and operations. We may well end up with the unit of design or code which is performing unrelated tasks. Any cohesion here would be accidental or coincidental cohesion. Coincidental cohesion does not usually happen in an initial design. However, as the design experiences multiple changes and modifications, e.g., due to requirements changes or bug fixes, and is under schedule pressures, the original design may evolve into a coincidental one. The original design may be patched to meet new requirements, or a related design may be adopted and modified instead of a fresh start. This will easily result in multiple unrelated elements in a design unit.

An Ordinal Scale for Cohesion Measurement

More reasonable design would have the contents of a module bear some relationship to each other. Different relationships can be created for the contents of each module. By identifying

Chapter 4

Software Measurement and Estimation

177

different types of module cohesion we can create a nominal scale for cohesion measurement. A stronger scale is an ordinal scale, which can be created by asking an expert to assess subjectively the quality of different types of module cohesion and create a rank-ordering. Here is an example ordinal scale for cohesion measurement: Rank Cohesion type Quality Good 6 Functional cohesion 5 Sequential cohesion 4 Communication cohesion 3 Procedural cohesion 2 Temporal cohesion 1 Logical cohesion 0 Coincidental cohesion Bad

Functional cohesion is judged to provide a tightest relationship because the design unit (module) performs a single well-defined function or achieves a single goal. Sequential cohesion is judged as somewhat weaker, because the design unit performs more than one function, but these functions occur in an order prescribed by the specification, i.e., they are strongly related. Communication cohesion is present when a design unit performs multiple functions, but all are targeted on the same data or the same sets of data. The data, however, is not organized in an object-oriented manner as a single type or structure. Procedural cohesion is present when a design unit performs multiple functions that are procedurally related. The code in each module represents a single piece of functionality defining a control sequence of activities. Temporal cohesion is present when a design unit performs more than one function, and they are related only by the fact that they must occur within the same time span. An example would be a design that combines all data initialization into one unit and performs all initialization at the same time even though it may be defined and utilized in other design units. Logical cohesion is characteristic of a design unit that performs a series of similar functions. At first glance, logical cohesion seems to make sense in that the elements are related. However, the relationship is really quite weak. An example is the Java class java.lang.Math, which contains methods for performing basic numeric operations such as the elementary exponential, logarithm, square root, and trigonometric functions. Although all methods in this class are logically related in that they perform mathematical operations, they are entirely independent of each other.
Ideally, object-oriented design units (classes) should exhibit the top two types of cohesion (functional or sequential), where operations work on the attributes that are common for the class. A serious issue with this cohesion measure is that the success of any module in attaining highlevel cohesion relies purely on human assessment.

Cohesion Measurement via Disjoint Sets of Instance variables

This metric considers the number of disjoint sets formed by the intersection of the sets of the instance variables used by each method. Consider a class C with m methods M1, , Mm, and a

Ivan Marsic

Rutgers University

178

attributes. Perfect cohesion is considered to be when all methods access all attributes. For this, we expect the lack of cohesion of methods (LCOM) metric to have a (fractional) value of 0. At the opposite end of the spectrum, consider that each method only accesses a single attribute (assuming that m = a). In this case, we expect LCOM = 1, which indicates extreme lack of cohesion. Consider a set of methods {Mi} (i = 1, , m} accessing a set of attributes {Aj} (j = 1, , a}. Let the number of attributes accessed by each method, Mi, be denoted as (Mi) and the number of methods which access each attribute be (Aj). Then the lack of cohesion of methods is given formally as

1 a (A j ) m a j =1 LCOM = 1 m

(4.7)

4.3.2

Semantic Cohesion

Cohesion or module strength refers to the notion of a module level togetherness viewed at the system abstraction level. Thus, although in a sense it can be regarded as a system design concept, we can more properly regard cohesion as a semantic concern expressed of a module evaluated externally to the module. Semantic cohesion is an externally discernable concept that assesses whether the abstraction represented by the module (class in object-oriented approach) can be considered to be a whole semantically. Semantic complexity metrics evaluate whether an individual class is really an abstract data type in the sense of being complete and also coherent. That is, to be semantically cohesive, a class should contain everything that one would expect a class with those responsibilities to possess but no more. It is possible to have a class with high internal, syntactic cohesion but little semantic cohesion. Individually semantically cohesive classes may be merged to give an externally semantically nonsensical class while retaining internal syntactic cohesion. For example, imagine a class that includes features of both a person and the car the person owns. Let us assume that each person can own only one car and that each car can only be owned by one person (a one-to-one association). Then person_id car_id, which would be equivalent to data normalization. However, classes have not only data but operations to perform various actions. They provide behavior patterns for (1) the person aspect and (2) the car aspect of our proposed class. Assuming no intersecting behavior between PERSON and CAR, then what is the meaning of our class, presumably named CAR_PERSON? Such a class could be internally highly cohesive, yet semantically as a whole class seen from outside the notion expressed (here of the thing known as a person-car) is nonsensical.

Chapter 4

Software Measurement and Estimation

179

(a)

(b)

Figure 4-3: Random arrays illustrate information complexity vs. depth. See text for details.

4.4 Psychological Complexity

One frustration with software complexity measurement is that, unlike placing a physical object on a scale and measuring its weight, we cannot put a software object on a complexity scale and read out the amount. Complexity seems to be an interpreted measure, much like persons health condition and it has to be stated as an average case. Your doctor can precisely measure your blood pressure, but a specific number does not necessarily correspond to good or bad health. The doctor will also measure your heart rate, body temperature, and perhaps several other parameters, before making an assessment about your health condition. Even so, the assessment will be the best guess, merely stating that on average such and such combination of physiological measurements corresponds to a certain health condition. Perhaps we should define software object complexity similarly: as a statistical inference based on a set of directly measurable variables.

4.4.1

Algorithmic Information Content

I already mentioned that our abstractions are unavoidably approximate. The term often used is coarse graining, which means that we are blurring detail in the world picture and single out only the phenomena we believe are relevant to the problem at hand. Hence, when defining complexity it is always necessary to specify the level of detail up to which the system is described, with finer details being ignored. One way of defining the complexity of a program or system is by means of its description, that is, the length of the description. I discussed above the merits of using size metrics as a complexity measure. Some problems mentioned above include: size could be measured differently; it depends on the language in which the program code (or any other accurate description of it) is written; and, the program description can be unnecessarily stuffed to make it appear complex. A way out is to ignore the language issue and define complexity in terms of the description length.

Ivan Marsic

Rutgers University

180

Suppose that two persons wish to communicate a system description at distance. Assume they are employing language, knowledge, and understanding that both parties share (and know they share) beforehand. The crude complexity of the system can be defined as the length of the shortest message that one party needs to employ to describe the system, at a given level of coarse graining, to the distant party. A well-known such measure is called algorithmic information content, which was introduced in 1960s independently by Andrei N. Kolmogorov, Gregory Chaitin, and Ray Solomonoff. Assume an idealized general-purpose computer with an infinite storage capacity. Consider a particular message string, such as aaaaabbbbbbbbbb. We want to know: what is the shortest possible program that will print out that string and then stop computing? Algorithmic information content (AIC) is defined as the length of the shortest possible program that prints out a given string. For the example string, the program may look something like: P a{5}b{10}, which means Print 'a' five times and 'b' ten times.

Information Theory

Logical Depth and Crypticity

...I think it better to write a long letter than incur loss of time... Cicero I apologize that this letter is so long. I did not have the time to make it short. Mark Twain If I had more time, I would have written a shorter letter. variously attributed to Cicero, Pascal, Voltaire, Mark Twain, George Bernard Shaw, and T.S. Elliot The price of reliability is the pursuit of the utmost simplicity. It is a price which the very rich may find hard to pay. C.A.R. Hoare

I already mentioned that algorithmic information content (AIC) does not exactly correspond to everyday notion of complexity because under AIC random strings appear as most complex. But there are other aspects to consider, as well. Consider the following description: letter X in a random array of letters L. Then the description letter T in a random array of letters L should have about the same AIC. Figure 4-3 pictures both descriptions in the manner pioneered by my favorite teacher Bela Julesz. If you look at both arrays, I bet that you will be able to quickly notice X in Figure 4-3(a), but you will spend quite some time scanning Figure 4-3(b) to detect the T! There is no reason to believe that human visual system developed a special mechanism to recognize the pattern in Figure 4-3(a), but failed to do so for the pattern in Figure 4-3(b). More likely, the same general pattern recognition mechanism operates in both cases, but with much less success on Figure 4-3(b). Therefore, it appears that there is something missing in the AIC notion of complexityan apparently complex description has low AIC. The solution is to include the computation time. Charles Bennett defined logical depth of a description to characterize the difficulty of going from the shortest program that can print the description to the actual description of the system. Consider not just the shortest program to print out the string, but a set of short programs that have

Chapter 4

Software Measurement and Estimation

181

Working memory Intelligent system

Chunking unit Chunking unit

Input sequence from the world (time-varying)

Figure 4-4: A model of a limited working memory. the same effect. For each of these programs, determine the length of time (or number of steps) needed to compute and print the string. Finally, average the running times so that shorter programs are given greater weight.

4.5 Effort Estimation

Adding manpower to a late software project makes it later. Frederick P. Brooks, Jr., The Mythical Man-Month A carelessly planned project will take only twice as long. The law of computerdom according to Golub The first 90 percent of the tasks takes 10 percent of the time and the last 10 percent takes the other 90 percent. The ninety-ninety rule of project schedules

Ivan Marsic

Rutgers University

182

4.5.1

Deriving Project Duration from Use Case Points

Use case points (UCP) are a measure of software size (Section 4.2.2). We can use equation (1.2) given in Section 1.2.5 to derive the project duration. For this purpose we need to know the teams velocity, which represents the teams rate of progress through the use cases (or, the teams productivity). Here is the equation that is equivalent to equation (1.2), but using a Productivity Factor (PF):

Duration = UCP PF

(4.8)

The Productivity Factor is the ratio of development person-hours needed per use case point. Experience and statistical data collected from past projects provide the data to estimate the initial PF. For instance, if a past project with a UCP of 112 took 2,550 hours to complete, divide 2,550 by 112 to obtain a PF of 23 person-hours per use case point. If no historical data has been collected, the developer can consider one of these options: 1. Establish a baseline by computing the UCP for projects previously completed by your team (if such are available). 2. Use a value for PF between 15 and 30 depending on the development teams overall experience and past accomplishments (Do they normally finish on time? Under budget? etc.). For a team of beginners, such as undergraduate students, use the highest value (i.e., 30) on the first project. A different approach was proposed by Schneider and Winters [2001]. Recall that the environmental factors (Table 4-7) measure the experience level of the people on your project and the stability of your project. Any negatives in this area mean that you will have to spend time training people or fixing problems due to instability (of requirements). The more negatives you have, the more time you will spend fixing problems and training people and less time you will have to devote to your project. Schneider and Winters suggested counting the number of environmental factors among E1 through E6 (Table 4-8) that have the perceived impact less than 3 and those among E7 and E8 with the impact greater than 3. If the total count is 2 or less, assume 20 hours per use case point. If the total is 3 or 4, assume 28 hours per use case. Any total greater than 4 indicates that there are too many environmental factors stacked against the project. The project should be put on hold until some environmental factors can be improved. Probably the best solution for estimating the Productivity Factor is to calculate your organizations own historical average from past projects. This is why collecting historic data is important for improving effort estimation on future projects. After a project completes, divide the number of actual hours it took to complete the project by the UCP number. The result becomes the new PF that can be used in the future projects. When estimating the duration in calendar time, is important to avoid assuming ideal working conditions. The estimate should account for corporate overheadanswering email, attending meetings, and so on. Suppose our past experience suggests a PF of 23 person-hours per use case point and our current project has 94 use case points (as determined Section 4.2.2). Equation (4.8) gives the duration as 94 23 = 2162 person-hours. Obviously, this does not imply that the project will be completed in 2162 / 24 90 days! A reasonable assumption is that each developer will

Chapter 4

Software Measurement and Estimation

183

spend about 30 hours per week on project tasks and the rest of their time will be taken by corporate overhead. With a team of four developers, this means the team will make 4 30 = 120 hours per week. Dividing 2162 person-hours by 120 hours per week we obtain a total of approximately 18 weeks to complete this project.

4.6 Summary and Bibliographical Notes

In this chapter I described two kinds of software measurements. One kind works with scarce artifacts that are available early on in a project, such as customer statement of requirements for the planned system. There is a major subjective component to these measurements, and it works mainly based on guessing and past experience with similar projects. The purpose of this kind of measurements is to estimate the project duration and cost of the effort, so to negotiate the terms of the contract with the customer who is sponsoring the project. The other kind of software measurements works with actual software artifacts, such as UML designs or source code. It aims to measure intrinsic properties of the software and avoid developers subjective guesses. Because it requires that the measured artifacts already exist in a completed or nearly completed condition, it cannot be applied early on in a project. The purpose of this kind of measurements is to evaluate the product quality. It can serve as a test of whether the product is ready for deployment, or to provide feedback to the development team about the potential weaknesses that need to be addressed. An early project effort estimate helps managers, developers, and testers plan for the resources a project requires. The use case points (UCP) method has emerged as one such method. It is a mixture of intrinsic software properties, measured by Unadjusted Use Case Points (UUCP) as well as technical (TCF) and environmental factors (ECF), which depend on developers subjective estimates. The UCP method quantifies these subjective factors into equation variables that can be adjusted over time to produce more precise estimates. Industrial case studies indicate that the UCP method can produce an early estimate within 20% of the actual effort.

Horst Zuse, History of Software Measurement, Technische Universitt Berlin, Online at: http://irb.cs.tu-berlin.de/~zuse/sme.html

[Halstead, 1977] distinguishes software science from computer science. The premise of software science is that any programming task consists of selecting and arranging a finite number of program tokens, which are basic syntactic units distinguishable by a compiler: operators and operands. He defined several software metrics based on these tokens. However, software science has been controversial since its introduction and has been criticized from many fronts. Halsteads work has mainly historical importance for software measurement because it was instrumental in making metrics studies an issue among computer scientists.

Ivan Marsic

Rutgers University

184

Use case points (UCP) were first described by Gustav Karner [1993], but his initial work on the subject is closely guarded by Rational Software, Inc. Hence, the primary sources describing Karners work are [Schneider & Winters, 2001] and [Ribu, 2001]. UCP was inspired by Allan Albrechts Function Point Analysis [Albrecht, 1979]. The weighted values and constraining constants were initially based on Albrecht, but subsequently modified by people at Objective Systems, LLC, based on their experience with Objectorya methodology created by Ivar Jacobson for developing object-oriented applications [26]. My main sources for use case points were [Schneider & Winters, 2001; Ribu, 2001; Cohn, 2005]. [Kusumoto, et al., 2004] describes the rules for a system that automatically computes the total UCP for given use cases. I believe these rules are very useful for a beginner human when computing UCPs for a project. Many industrial case studies verified the estimation accuracy of the UCP method. These case studies found that the UCP method can produce an early estimate within 20% of the actual effort, and often closer to the actual effort than experts or other estimation methodologies. Mohagheghi et al. [2005] described the UCP estimate of an incremental, large-scale development project that was within 17% of the actual effort. Carroll [2005] described a case study over a period of five years and across more than 200 projects. After applying the process across hundreds of sizable software projects (60 person-months average), they achieved estimating accuracy of less than 9% deviation from actual to estimated cost on 95% of the studied projects. To achieve greater accuracy, Carrolls estimation method includes a risk coefficient in the UCP equation.

Coupling and cohesion: [Constantine et al., 1974; Eder et al., 1992; Allen & Khoshgoftaar, 1999; Henry & Gotterbarn, 1996; Mitchell & Power, 2005] See also: http://c2.com/cgi/wiki?CouplingAndCohesion

[Henderson-Sellers, 1996] provides a condensed review of software metrics up to the publication date, so it is somewhat outdated. It is technical and focuses on metrics of structural complexity.

B. Henderson-Sellers, L. L. Constantine, and I. M. Graham, Coupling and cohesion: Towards a valid suite of object-oriented metrics, Object-Oriented Systems, vol. 3, no. 3, 143-158, 1996.

[Bennett, 1986; 1987; 1990] discusses definition of complexity for physical systems and defines logical depth.

Chapter 4

Software Measurement and Estimation

185

Problems
Problem 4.1

Problem 4.2

Problem 4.3
(CYCLOMATIC/MCCABE COMPLEXITY) Consider the following quicksort sorting algorithm: QUICKSORT(A, p, r) 1 if p < r 2 then q PARTITION(A, p, r) 3 QUICKSORT(A, p, q 1) 4 QUICKSORT(A, q + 1, r) where the PARTITION procedure is as follows: PARTITION(A, p, r) 1 x A[r] 2 ip1 3 for j p to r 1 4 do if A[j] x 5 then i i + 1 6 exchange A[i] A[j] 7 exchange A[i + 1] A[r] 8 return i + 1 (a) Draw the flowchart of the above algorithm. (b) Draw the corresponding graph and label the nodes as n1, n2, and edges as e1, e2, (c) Calculate the cyclomatic complexity of the above algorithm.

Problem 4.4

Design with Patterns

Chapter 5

Contents
It is not the strongest of the species that survive, nor the most intelligent, but the one most responsive to change. Charles Darwin Man has a limited biological capacity for change. When this capacity is overwhelmed, the capacity is in future shock. Alvin Toffler

5.1 Indirect Communication: PublisherSubscriber

5.1.1 Control Flow 5.1.2 Pub-Sub Pattern Initialization 5.1.3 5.1.4 5.1.5

Design patterns have recently become a strong trend in an effort to cope with software complexity. The text that most contributed to the popularity of patterns is [Gamma et al., 1995]. Patterns are means for documenting recurring microarchitectures of software. They are abstractions of common object structures that expert developers apply to solve software design problems. The power of design patterns derives from codifying practice rather than prescribing practice, i.e., they are capturing the existing best practices, rather than inventing untried procedures. Design patterns can be of different complexities and for different purposes. In terms of complexity, the design pattern may be as simple as a naming convention for object methods in the JavaBeans specification (see Chapter 7) or can be a complex description of interactions between the multiple classes, some of which will be reviewed in this chapter. In terms of the purpose, a pattern may be intended to facilitate component-based development and reusability, such as in the JavaBeans specification, or its purpose may be to prescribe the rules for responsibility assignment to the objects in a system, as with the design principles described in Section 2.5.

5.2 More Patterns

5.2.1 Command 5.2.2 Proxy 5.2.3 5.2.4

5.3 Concurrent Programming

5.3.1 Threads 5.3.2 Exclusive Resource AccessExclusion Synchronization 5.3.3 Cooperation between ThreadsCondition Synchronization 5.3.4 5.2.3

5.4 Broker and Distributed Computing

5.4.1 Broker Pattern 5.4.2 Java Remote Method Invocation (RMI) 5.4.3 5.4.4

5.5 Information Security

5.5.1 Symmetric and Public-Key Cryptosystems 5.5.2 Cryptographic Algorithms 5.5.3 Authentication 5.5.4

5.6 Summary and Bibliographical Notes Problems

As pointed earlier, finding effective representation(s) is a recurring theme of software engineering. By condensing many structural and behavioral aspects of the design into a few simple concepts, patterns make it easier for team members to discuss the design. As with any symbolic language, one of the greatest benefits of patterns is in chunking the design knowledge. Once team members are familiar with the pattern terminology, the use of this terminology shifts the focus to higher-level design concerns. No time is spent in describing the mechanics of the object collaborations because they are condensed into a single pattern name.

186

Chapter 5

Design with Patterns

187

Custodian Custodian

initializes the pattern

Instantiation of the Instantiation of the Design Pattern Design Pattern Client Client collection of objects working to provide service

asks for service

Figure 5-1: The players in a design pattern usage. This chapter reviews some of the most popular design patterns that will be particularly useful in the rest of the text. What follows is a somewhat broad and liberal interpretation of design patterns. The focus is rather on the techniques of solving specific problems; nonetheless, the patterns described below do fit the definition of patterns as recurring solutions. These patterns are conceptual tools that facilitate the development of flexible and adaptive applications as well as reusable software components. Two important observations are in order. First, finding a name that in one or few words conveys the meaning of a design pattern is very difficult. A similar difficulty is experienced by user interface designers when trying to find graphical icons that convey the meaning of user interface operations. Hence, the reader may find the same or similar software construct under different names by different authors. For example, The Publisher-Subscriber design pattern, described in Section 5.1, is most commonly called Observer [Gamma et al., 1995], but [Larman, 2005] calls it Publish-Subscribe. I prefer the latter because I believe that it conveys better the meaning of the underlying software construct1. Second, there may be slight variations in what different authors label with the same name. The difference may be due to the particular programming language idiosyncrasies or due to evolution of the pattern over time. Common players in a design pattern usage are shown in Figure 5-1. A Custodian object assembles and sets up a pattern and cleans up after the patterns operation is completed. A client object (can be the same software object as the custodian) needs and uses the services of the pattern. The design patterns reviewed below generally follow this usage pattern.

5.1 Indirect Communication: PublisherSubscriber

If you find a good solution and become attached to it, the solution may become your next problem. Robert Anthony

The Publish-Subscribe moniker has a broader use than presented here and the interested reader should consult [Eugster et al. 2003].

Ivan Marsic

Rutgers University

188

Subscribers

Publisher

Figure 5-2: The concept of indirect communication in a Publisher/Subscriber system. Publisher-subscriber design pattern (see Figure 5-2) is used to implement indirect communication between software objects. Indirect communication is usually used when an object cannot or does not want to know the identity of the object whose method it calls. Another reason may be that it does not want to know what the effect of the call will be. The most popular use of the pub-sub pattern is in building reusable software components. 1) Enables building reusable components 2) Facilitates separation of the business logic (responsibilities, concerns) of objects Centralized vs. decentralized execution/program-control methodspreads responsibilities for better balancing. Decentralized control does not necessarily imply concurrent threads of execution. The problem with building reusable components can be illustrated on our case-study example. Let us assume that we want to reuse the KeyChecker object in an extended version of our case-study application, one that sounds alarm if someone is tampering with the lock. We need to modify the method unlock() not only to send message to LockCtrl but also to AlarmCtrl, or to introduce a new method. In either case, we must change the object code, meaning that the object is not reusable as-is. Information source acquires information in some way and we assume that this information is important for other objects to do the work they are designed for. Once the source acquires information (becomes information expert), it is logical to expect it to pass this information to

Chapter 5

Design with Patterns

189

Publisher
Knowing Responsibilities: Knows event source(s) Knows interested objs (subscribers) Doing Responsibilities: Registers/Unregisters subscribers Notifies the subscribers of events

interface Publisher + subscribe() + unsubscribe()

* subscribers

interface Subscriber + receive()

Subscriber
Knowing Responsibilities: Knows event types of interest Knows publisher(s) Doing Responsibilities: Registers/Unregisters with publishers Processes received event notifications
Type1Publisher + subscribe() + unsubscribe() Type2Publisher + subscribe() + unsubscribe() Type1Subscriber + receive()

(a)

(b)

Figure 5-3: (a) Publisher/Subscriber objects employee cards. (b) The Pub-Sub design pattern (class diagram). The base Publisher/Subscriber type is usually defined as interface. others and initiate their work. However, this tacitly implies that the source object knows what the doer object should do next. This knowledge is encoded in the source object as an IF-THENELSE rule and must be modified every time the doer code is modified (as seen earlier in Section 2.5). Request- vs. event-based communication, Figure 5-4: In the former case, an object makes an explicit request, whereas in the latter, the object expresses interest ahead of time and later gets notified by the information source. In a way, the source is making a method request on the object. Notice also that request-based is also synchronous type of communication, whereas event based is asynchronous. Another way to design the KeyChecker object is to make it become a publisher of events as follows. We need to define two class interfaces: Publisher and Subscriber (see Figure 5-3). The first one, Publisher, allows any object to subscribe for information that it is the source of. The second, Subscriber, has a method, here called receive(), to let the Publisher publish the data of interest.

Listing 5-1: Publish-Subscribe class interfaces.

public interface Subscriber { public void receive(Content content); } import java.util.ArrayList; public class Content { public Publisher source_; public ArrayList data_;

Ivan Marsic

Rutgers University

190

Request: doSomething(info) Info Info Src Src Doer Doer

Request: getInfo() Info Info Src Src info Doer Doer

(1) Request: subscribe() Info Info Src Src (2) event (info) Doer Doer

(a)

(b)

(c)

Figure 5-4: Request- vs. event-based communication among objects. (a) Direct request information source controls the activity of the doer. (b) Direct requestthe doer controls its own activity, information source is only for lookup, but doer must know when is the information ready and available. (c) Indirect requestthe doer controls its own activity and does not need to worry when the information is ready and availableit gets prompted by the information source.

public Content(Publisher src, ArrayList dat) { source_ = src; data_ = (ArrayList) dat.clone(); // for write safety... } // ...avoid aliasing and create a new copy } public interface Publisher { public subscribe(Subscriber subscriber); public unsubscribe(Subscriber subscriber); }

A Content object contains only data, no business logic, and is meant to transfer data from Publisher to Subscriber. The actual classes then implement these two interfaces. In our example, the key Checker object would then implement the Publisher, while LockCtrl, AlarmCtrl, and others would implement the Subscriber.

Listing 5-2: Refactored the case-study code of using the Publisher-Subscriber design pattern. Here, the class LightCtrl implements the Subscriber interface and the class Checker implements the Publisher interface.
public class LightCtrl implements Subscriber { protected LightBulb bulb_; protected PhotoSObs sensor_; public LightCtrl(Publisher keyChecker, PhotoSObs sensor, ... ) { sensor_ = sensor; keyChecker.subscribe(this); ... } public void receive(Content content) { if (content.source_ instanceof Checker) { if ( ((String)content.data_).equals("valid") ) {

Chapter 5

Design with Patterns

191

// check the time of day; if daylight, do nothing if (!sensor_.isDaylight()) bulb_.setLit(true); } } else (check for another source of the event ...) { ... } } } import java.util.ArrayList; import java.util.Iterator; public class Checker implements Publisher { protected KeyStorage validKeys_; protected ArrayList subscribers_ = new ArrayList(); public Checker( ... ) { } public subscribe(Subscriber subscriber) { subscribers_.add(subscriber); // could check whether this } // subscriber already subscribed public unsubscribe(Subscriber subscriber) { int idx = subscribers_.indexOf(subscriber); if (idx != -1) { subscribers_.remove(idx); } } public void checkKey(Key user_key) { boolean valid = false; ... // verify the user key against the "validKeys_" database // notify the subscribers Content cnt = new Content(this, new ArrayList()); if (valid) { // authorized user cnt.data.add("valid"); } else { // the lock is being tampered with cnt.data.add("invalid"); } cnt.data.add(key); for (Iterator e = subscribers_.iterator(); e.hasNext(); ) { ((Subscriber) e.next()).receive(cnt); } } }

Ivan Marsic

Rutgers University

192

: Controller enterKey()

k : Key

: Checker

: KeyStorage

: LockCtrl

: PhotoSObs

: LightCtrl

: AlarmCtrl

: Logger

k := create() checkKey(k) loop sk := getNext() compare()

alt loop

valid == true for all KeyIsValid subscribers keyIsValid() keyIsValid() keyIsValid() dl := isDaylight() opt dl == false setLit(true)

[else] loop prompt: "try again" keyIsInvalid() opt numOfTrials == maxNumOfTrials soundAlarm() keyIsInvalid() for all KeyIsInvalid subscribers keyIsInvalid() numOfTrials++

Figure 5-5: Sequence diagram for publish-subscribe version of the use case Unlock. Compare this with Figure 2-17. A Subscriber may be subscribed to several sources of data and each source may provide several types of content. Thus, the Subscriber must determine the source and the content type before it takes any action. If a Subscriber gets subscribed to many sources which publish different content, the Subscriber code may become quite complex and difficult to manage. The Subscriber would contain many if()or switch() statements to account for different options. A more objectoriented solution for this is to use class polymorphisminstead of having one Subscriber, we should have several Subscribers, each specialized for a particular source. The Subscribers may also have more than one receive() method, each specialized for a particular data type. Here is an example. We could implement a Switch by inheriting from the generic Subscriber interface defined above, or we can define new interfaces specialized for our problem domain.

Listing 5-3: Subscriber interfaces for key-is-valid and key-is-invalid events.

public interface KeyIsValidSubscriber { public void keyIsValid(LockEvent event); // receive() method } public interface KeyIsInvalidSubscriber { public void keyIsInvalid(LockEvent event); // receive() method

Chapter 5

Design with Patterns

193

The new design for the Unlock use case is shown in Figure 5-5, and the corresponding code might look as shown next. Notice that here the attribute numOfTrials belongs to the AlarmCtrl, unlike the first implementation in Listing 2-2 (Section 2.7), where it belonged to the Controller. Notice also that the Controller is a KeyIsInvalidSubscriber so it can prompt the user to enter a new key if the previous attempt was unsuccessful.

Listing 5-4: A variation of the Publisher-Subscriber design from Listing 5-2 using the subscriber interfaces from Listing 5-3.
public class Checker implements LockPublisher { protected KeyStorage validKeys_; protected ArrayList keyValidSubscribers_ = new ArrayList(); protected ArrayList keyInvalidSubscribers_ = new ArrayList(); public Checker(KeyStorage ks) { validKeys_ = ks; } public subscribeKeyIsValid(KeyIsValidSubscriber sub) { keyValidSubscribers_.add(sub); } public subscribeKeyIsInvalid(KeyIsInvalidSubscriber sub) { keyInvalidSubscribers_.add(sub); } public void checkKey(Key user_key) { boolean valid = false; ... // verify the key against the database // notify the subscribers LockEvent evt = new LockEvent(this, new ArrayList()); evt.data.add(key); if (valid) { for (Iterator e = keyValidSubscribers_.iterator(); e.hasNext(); ) { ((KeyIsValidSubscriber) e.next()).keyIsValid(evt); } } else { // the lock is being tampered with for (Iterator e = keyInvalidSubscribers_.iterator(); e.hasNext(); ) { ((KeyIsInvalidSubscriber) e.next()).keyIsInvalid(evt); } } } } public class LightCtrl implements KeyIsValidSubscriber { protected LightBulb bulb_; protected PhotoSObs photoObserver_; public LightCtrl(LockPublisher keyChecker, PhotoSObs sensor, ... ) { photoObserver_ = sensor;

Ivan Marsic

Rutgers University

194

keyChecker.subscribeKeyIsValid(this); ... } public void keyIsValid(LockEvent event) { if (!photoObserver_.isDaylight()) bulb_.setLit(true); } } public class AlarmCtrl implements KeyIsInvalidSubscriber { public static final long maxNumOfTrials_ = 3; public static final long interTrialInterval_ = 300000; // millisec protected long numOfTrials_ = 0; protected long lastTime_ = 0; public AlarmCtrl(LockPublisher keyChecker, ...) { keyChecker.subscribeKeyIsInvalid(this); ... } public void keyIsInvalid(LockEvent event) { long currTime = System.currentTimeMillis(); if ((currTime lastTime_) < interTrialInterval_) { if (++numOfTrials_ >= maxNumOfTrials_) { soundAlarm(); numOfTrials_ = 0; // reset for the next user } } else { // this must be a new user's first mistake ... numOfTrials_ = 1; } lastTime_ = currTime; } }

It is of note that what we just did with the original design for the Unlock use case can be considered refactoring. In software engineering, the term refactoring is often used to describe modifying the design and/or implementation of a software module without changing its external behavior, and is sometimes informally referred to as cleaning it up. Refactoring is often practiced as part of the software development cycle: developers alternate between adding new tests and functionality and refactoring the code to improve its internal consistency and clarity. In our case, the design from Figure 2-17 has been transformed to the design in Figure 5-5. There is a tradeoff between the number of receive() methods and the switch() statements. On one hand, having a long switch() statement complicates the Subscribers code and makes it difficult to maintain and reuse. On the other hand, having too many receive() statements results in a long class interface, difficult to read and represent graphically.

5.1.1

Applications of Publisher-Subscriber

The Publisher-Subscriber design pattern is used in the Java AWT and Swing toolkits for notification of the GUI interface components about user generated events. (This pattern in Java is known as Source-Listener or delegation event model, see Chapter 7.)

Chapter 5

Design with Patterns

195

One of the main reasons for software components is easy visualization in integrated development environments (IDEs), so the developer can visually assemble the components. The components are represented as integrated circuits in analogy to hardware design, and different receive() / subscribe() methods represent pins on the circuit. If a component has too many pins, it becomes difficult to visualize, and generates too many wires in the blueprint. The situation is similar to determining the right number of pins on an integrated circuit. (See more about software components in Chapter 7.) Here I reiterate the key benefits of using the pub-sub design pattern and indirect communication in general:

The components do not need to know each others identity. For example, in the sample code given in Listing 1-1 (Section 1.4.2), LockCtrl maintains a reference to a LightCtrl object. The components business logic is contained within the component alone. In the same example, LockCtrl explicitly invokes the LightCtrls method setLit(), meaning that it minds LightCtrls business. In the worst case, even the checking of the time-of-day may be delegated to LockCtrl in order to decide when to turn the light on.

Both of the above form the basis for component reusability, because making a component independent of others makes it reusable. The pub-sub pattern is the most basic pattern for reusable software components as will be discussed in Chapter 7. In the ideal case, all objects could be made self-contained and thus reusable by applying the pub-sub design pattern. However, there are penalties to pay. As visible from the examples above, indirect communication requires much more code, which results in increased demand for memory and decreased performance. Thus, if it is not likely that a component will need to be reused or if performance is critical, direct communication should be applied and the pub-sub pattern should be avoided. When to apply the pub-sub pattern? The answer depends on whether you anticipate that the component is likely to be reused in future projects. If yes, apply pub-sub. You should understand that decoupled objects are independent, therefore reusable and easier to understand, while highly interleaved objects provide fast inter-object communication and compact code. Decoupled objects are better suited for global understanding, whereas interleaved objects are better suited for local understanding. Of course, in a large system, global understanding matters more.

5.1.2

Control Flow

Figure 5-6 highlights the difference in control flow for direct and indirect communication types. In the former case, the control is centralized and all flows emanate from the Controller. In the latter case, the control is decentralized, and it is passed as a token around, cascading from object to object. These diagrams also show the dynamic (behavioral) architecture of the system.

Ivan Marsic

Rutgers University
: Key getNext() : KeyStorage

196

create() checkKey() : Logger logTransaction() : Controller

: Checker

setOpen() : LockCtrl isDaylight()

soundAlarm() : AlarmCtrl

setLit() : PhotoSObs create() : Key : Checker getNext() : KeyStorage checkKey()

: LightCtrl : Controller keyIsInvalid() keyIsValid()

(a)

: LockCtrl : AlarmCtrl : Logger : LightCtrl

isDaylight()

(b)

: PhotoSObs

Figure 5-6: Flow control without (a) and with the Pub-Sub pattern (b). Notice that these UML communication diagrams are redrawn from Figure 2-17 and Figure 5-5, respectively. Although in Figure 5-6(b) it appears as if the Checker plays a central role, this is not so because it is not aware of being assigned such a role, i.e., unlike the Controller from Figure 5-6(a), this Checker does not encode the requisite knowledge to play such a role. The outgoing method calls are shown in dashed lines to indicate that these are indirect calls, through the Subscriber interface. Whatever the rules of behavior are stored in one Controller or distributed (cascading) around in many objects, the output (seen from outside of the system) is the same. Organization (internal function) matters only if it simplifies the software maintenance and upgrading.

Chapter 5

Design with Patterns

197

: Controller create()

: Checker

: LockCtrl

: LightCtrl

: AlarmCtrl

: Logger

subscribeKeyIsInvalid()

subscribeKeyIsValid()

A method call that passes a reference to the Checker

subscribeKeyIsValid()

subscribeKeyIsInvalid()

subscribeKeyIsValid() subscribeKeyIsInvalid()

Figure 5-7: Initialization of the pub-sub for the lock control example.

5.1.3

Pub-Sub Pattern Initialization

Note that the setup part of the pattern, example shown in Figure 5-7, plays a major, but often ignored, role in the pattern. It essentially represents the master plan of solving the problem using the publish-subscribe pattern and indirect communication. Most programs are not equipped to split hard problems into parts and then use divide-andconquer methods. Few programs, too, represent their goals, except perhaps as comments in their source codes. However, a class of programs, called General Problem Solver (GPS), was developed in 1960s by Allen Newel, Herbert Simon, and collaborators, which did have explicit goals and subgoals and solved some significant problems [Newel & Simon, 1962]. I propose that goal representation in object-oriented programs be implemented in the setup part of the program, which then can act at any time during the execution (not only at the initialization) to rewire the object relationships.

5.2 More Patterns

Publisher-Subscriber belongs to the category of behavioral design patterns. Behavioral patterns separate the interdependent behavior of objects from the objects themselves, or stated differently, they separate functionality from the object to which the functionality applies. This promotes reuse, because different types of functionality can be applied to the same object, as needed. Here I review Command as another behavioral pattern. Another category is structural patterns. An example structural pattern reviewed later is Proxy.

Ivan Marsic

Rutgers University
create( params )

198

doAction( params ) Client Client A A Server Server B B Invoker Invoker A A

execute()

doAction( params ) Command Command Receiver Receiver B B

unexecute()

(a)

(b)

Figure 5-8: Command pattern interposes Command (and other) objects between a client and a server object. Complex actions about rolling back and forward the execution history are delegated to the Command, away from the Invoker. A common drawback of design patterns, particularly behavioral patterns, is that we are replacing what would be a single method call with many method calls. This results in performance penalties, which in certain cases may not be acceptable. However, in most cases the benefits of good design outweigh the performance drawbacks.

5.2.1

Command

The key idea of the Command pattern is to support rollback of users actions in an elegant fashion. Anyone who uses computers appreciates the value of being able to undo their recent actions. Objects invoke methods on other objects as depicted in Figure 1-22, which is abstracted in Figure 5-8(a). The need for the Command pattern arises if the invoking object (client) needs to reverse the effect of a previous method invocation. Another reason is the ability to trace the course of the system operation. For example, we may need to keep track of financial transactions for legal or auditing reasons. The purpose of the Command patter is to delegate the functionality associated with rolling back the server objects state and logging the history of the system operation away from the client object to the Command object, see Figure 5-8(b). Instead of directly invoking a method on the Receiver (server object), the Invoker (client object) appoints a Command for this task. The Command pattern (Figure 5-9) encapsulates an action or processing task into an object thus increasing flexibility in calling for a service. Command represents operations as classes and is used whenever a method call alone is not sufficient. The Command object is the central player in the Command pattern, but as with most patterns, it needs other objects to assist with accomplishing the task. At runtime, a control is passed to the execute() method of a non-abstract-class object derived from Command . Figure 5-10(a) shows a sequence diagram on how to create and execute a command. The ability to reverse a commands effect is one of the common reasons for using the Command pattern. Another reason is the ability to trace the course of the system operation. For example, we may need to keep track of financial transactions for legal or auditing reasons. CommandHistory maintains history log of Commands in linear sequence of their execution. Figure 5-10(b) shows a sequence diagram on how to undo/redo a command, assuming that it is undoable. Observe also that CommandHistory decrements its pointer of the current command every time a command is undone and increments it every time a command is redone.

Chapter 5

Design with Patterns

199

Command
Knowing Responsibilities: Knows receiver of action request Knows whether action is reversible Doing Responsibilities: Executes an action Undoes a reversible action

Invoker

interface Command + execute() + unexecute() + isReversible() : boolean

Receiver1 + doAction1()

receiver

ActionType1Cmd + execute() + unexecute() + isReversible()

ActionType2Cmd + execute() + unexecute() + isReversible()

Receiver2

receiver

(a)

+ doAction2()

(b)

Figure 5-9: (a) Command object employee card. (b) The Command design pattern (class diagram). The base Command class is usually implemented as an interface. An additional requirement for CommandHistory is to manage properly the undo/redo caches. For example, if the user backs up along the undo queue and then executes a new command, the whole redo cache should be flushed. Similarly, upon a context switching, both undo/redo caches should be flushed. Obviously, this does not provide for long-term archiving of the commands; if that is required, the archive should be maintained independently of the undo/redo caches. It is common to use Command pattern in operating across the Internet. For example, suppose that client code needs to make a function call on an object of a class residing on a remote server. It is not possible for the client code to make an ordinary method call on this object because the remote object cannot appear in the usual compile-execute process. It is also difficult to employ remote method invocation (RMI) here because we often cannot prepare client and server in advance, except to give the client specification of the servlets file name. Instead, the call is made from the client by pointing the browser to the file containing the servlet. The servlet then calls its service(HttpServletRequest, HttpServletResponse) method. The object HttpServletRequest includes all the information that a method invocation requires, such as argument values, obtained from the environment variables at standardized global locations. The object HttpServletResponse carries the result of invoking service(). This technique embodies the basic idea of the Command design pattern. Web services allow a similar runtime function discovery and invocation, as will be seen in Chapter 8.

5.2.2

Proxy

Proxy is needed when the logistics of accessing another objects services (sending messages to it) is overly complex and requires great expertise. In such cases, the code surrounding the other objects method invocation becomes comparable or even greater in size than the code of the objects primary expertise. Instead of making the client object (invoker) more complex, we can introduce a proxy of the server object (subject), see Figure 5-11. Proxy is a surrogate used to stand in for the actual subject object and control/enhance access to it. The causes of access complexity include:

Ivan Marsic

Rutgers University

200

custodian

invoker

cmd : Command

receiver

: CommandHistory

create(receiver, args) accept(cmd)

(a)

execute() doAction(args)

log(cmd)

invoker

: CommandHistory undo()

: Command

receiver

isReversible()

opt

(b)

reversible == true unexecute()

doInverseAction()

setCurrentCmdPtr()

Figure 5-10: (a) Sequence diagram for creating and executing a command. (b) Sequence diagram for undoing a (reversible) command.

Receiver is located in a remote address space, e.g., on a remote host, in which case the invocation requires following complex networking protocols Receiver access should be filtered for security purposes or to enforce certain constraints, such as an upper limit on the number of accesses Deferred instantiation of the receiver, because its full functionality may not be (immediately) necessary; for example, a graphics editor can be started faster if images are not loaded initially and only empty boxes are shown instead, while image proxies make this process transparent for the rest of the program

In all these examples, the additional functionality is extraneous to the objects business logic. The proxy object abstracts the details of the logistics of accessing the receivers services. It does this transparently, so the client has an illusion it is directly communicating with the receiver. The Proxy pattern will be incorporated into a more complex Broker pattern in Section 5.4.

Chapter 5

Design with Patterns

Invoker interface Subject + request()

201

Proxy
Knowing Responsibilities: Knows real recipient of requests Knows how to deliver the requests Doing Responsibilities: Intercepts & preprocesses requests; may forward to the real recipient Returns result to the invoker

RealSubject + request()

realSubject

Proxy + request()

(a)

(b)

Figure 5-11: (a) Proxy object employee card. (b) The Proxy design pattern (class diagram).

5.3 Concurrent Programming

The test of a first-rate intelligence is the ability to hold two opposed ideas in mind at the same time and still retain the ability to function. F. Scott Fitzgerald

The benefits of concurrent programming include better use of multiple processors and easier programming of reactive (event-driven) applications. In event-driven applications, such as graphical user interfaces, the user expects a quick response from the system. If the (singleprocessor) system processes all requests sequentially, then it will respond with significant delays and most of the requestors will be unhappy. A common technique is to employ time-sharing or time slicinga single processor dedicates a small amount of time for each task, so all of them move forward collectively by taking turns on the processor. Although none of the tasks progresses as fast as it would if it were alone, none of them has to wait as long as it could have if the processing were performed sequentially. The task executions are really sequential but interleaved with each other, so they virtually appear as concurrent. In the discussion below I ignore the difference between real concurrency, when the system has multiple processors, and virtual concurrency on a single-processor system. From the users viewpoint, there is no logical or functional difference between these two optionsthe user would only see difference in the length of execution time. Computer process is, roughly speaking, a task being executed by a processor. A task is defined by a temporally ordered sequence of instructions (program code) for the processor. In general, a process consists of:

Memory, which contains executable program code and/or associated data Operating system resources that are allocated to the process, such as file descriptors (Unix terminology) or handles (Windows terminology) Security attributes, such as the identity of process owner and the processs set of privileges Processor state, such as the content of registers, physical memory addresses, etc. The state is stored in the actual registers when the process is executing, and in memory otherwise

Ivan Marsic

Rutgers University

202

yield()

Alive Blocked
wait()

Runnable
start()

New

Ready
interrupt()

Waiting for notification

notify() or notifyAll()

Waiting for I/O or lock

join()

Waiting for rendezvous

Target finishes sleep()

run() returns

Dead

Interrupted

Sleeping
Time out

interrupt() / throws InterruptedException

Figure 5-12: State diagram representing the lifecycle of Java threads. (State diagram notation is defined in Section 3.2.2.)

Threads are similar to processes, in that both represent a single sequence of instructions executed in parallel with other sequences, either by time slicing on a single processor or multiprocessing. A process is an entirely independent program, carries considerable state information, and interacts with other processes only through system-provided inter-process communication mechanisms. Conversely, a thread directly shares the state variables with other threads that are part of the same process, as well as memory and other resources. In this section I focus on threads, but many concepts apply to processes as well.
So far, although I promoted the metaphor of an object-based program as a bucket brigade, the objects carried their tasks sequentially, one after another, so in effect the whole system consists of a single worker taking the guises one-by-one of different software objects. Threads allow us to introduce true parallelism in the system functioning. Subdividing a problem to smaller problems (subtasks) is a common strategy in problem solving. It would be all well and easy if the subtasks were always disjoint, clearly partitioned and independent of each other. However, during the execution the subtasks often operate on the same resources or depend on results of other task(s). This is what makes concurrent programming complex: threads (which roughly correspond to subtasks) interact with each other and must coordinate their activities to avoid incorrect results or undesired behaviors.

5.3.1

Threads

A thread is a sequence of processor instructions, which can share a single address space with other threadsthat is, they can read and write the same program variables and data structures. Threads are a way for a program to split itself into two or more concurrently running tasks. It is a basic unit of program execution. A common use of threads is in reactive applications, having one thread paying attention to the graphical user interface, while others do long calculations in the background. As a result, the application more readily responds to users interaction.

Chapter 5

Design with Patterns

203

Figure 5-12 summarizes different states that a thread may go through in its lifetime. The three main states and their sub-states are: 1. New: The thread object has been created, but it has not been started yet, so it cannot run 2. Alive: After a thread is started, it becomes alive, at which point it can enter several different sub-states (depending on the method called or actions of other threads within the same process): a. Runnable: The thread can be run when the time-slicing mechanism has CPU cycles available for the thread. In other words, when there is nothing to prevent it from being run if the scheduler can arrange it b. Blocked: The thread could be run, but there is something that prevents it (e.g., another thread is holding the resource needed for this thread to do its work). While a thread is in the blocked state, the scheduler will simply skip over it and not give it any CPU time, so the thread will not perform any operations. As visible from Figure 5-12, a thread can become blocked for the following reasons: i. Waiting for notification: Invoking the method wait() suspends the thread until the thread gets the notify() or notifyAll() message ii. Waiting for I/O or lock: The thread is waiting for an input or output operation to complete, or it is trying to call a synchronized method on a shared object, and that objects lock is not available iii. Waiting for rendezvous: Invoking the method join(target) suspends the thread until the target thread returns from its run() method iv. Sleeping: Invoking the method sleep(milliseconds) suspends the thread for the specified time 3. Dead: This normally happens to a thread when it returns from its run() method. A dead thread cannot be restarted, i.e., it cannot become alive again The meaning of the states and the events or method invocations that cause state transitions will become clearer from the example in Section 5.3.4. A thread object may appear as any other software object, but there are important differences. Threads are not regular objects, so we have to be careful with their interaction with other objects. Most importantly, we cannot just call a method on a thread object, because that would execute the given method from our current threadneglecting the thread of the methods objectwhich could lead to conflict. To pass a message from one thread to another, we must use only the methods shown in Figure 5-12. No other methods on thread objects should be invoked. If two or more threads compete for the same resource which can be used by only one at a time, then their access must be serialized, as depicted in Figure 5-13. One of them becomes blocked while the other proceeds. We are all familiar with conflicts arising from people sharing resources. For example, people living in a house/apartment share the same bathroom. Or, many people may be sharing the same public payphone. To avoid conflicts, people follow certain protocols, and threads do similarly.

Ivan Marsic
Thread 1

Rutgers University
Shared Resource

204

Thread 2

RA IL

SIN R OS OA D CR

RA IL

G SIN R OS OA D CR

RA

SIN R OS OA D CR

IL

Step 1: Lock

Step 2: Use

Step 3: Unlock

Figure 5-13: Illustration of exclusion synchronization. The lock simply ensures that concurrent accesses to the shared resource are serialized.

5.3.2

Exclusive Resource AccessExclusion Synchronization

If several threads attempt to access and manipulate the same data concurrently a race condition or race hazard exists, and the outcome of the execution depends on the particular order in which the access takes place. Consider the following example of two threads simultaneously accessing the same banking account (say, husband and wife interact with the account from different branches): Thread 1
oldBalance = account.getBalance(); newBalance = oldBalance + deposit; account.setBalance(newBalance); ...

Thread 2
... oldBalance = account.getBalance(); newBalance = oldBalance - withdrawal; account.setBalance(newBalance);

The final account balance is incorrect and the value depends on the order of access. To avoid race hazards, we need to control access to the common data (shared with other threads) and make the access sequential instead of parallel. A segment of code in which a thread may modify shared data is known as a critical section or critical region. The critical-section problem is to design a protocol that threads can use to avoid interfering with each other. Exclusion synchronization, or mutual exclusion (mutex), see Figure 5-14, stops different threads from calling methods on the same object at the same time and thereby jeopardizing the integrity of the shared data. If thread is executing in its critical region then no other thread can be

DING

DING

I THINK I CAN, I THINK I CAN, I THINK I CAN...

DING

DING

Chapter 5

Design with Patterns

205

thrd1 : Thread

shared_obj : Object

thrd2 : Thread

Critical region; the code fragment can have only one thread executing it at once.

region

obtain lock obtain lock Successful: thrd1 locks itself in & does the work release lock Unsuccessful: thrd2 blocked and waiting for the shared object to become vacant transfer lock

Lock transfer controlled by operating system and hardware

thrd2 acquires the lock & does the work

Figure 5-14: Exclusion synchronization pattern for concurrent threads. executing in its critical region. Only one thread is allowed in a critical region at any moment. Java provides exclusion synchronization through the keyword synchronized, which simply labels a block of code that should be protected by locks. Instead of the programmer explicitly acquiring or releasing the lock, synchronized signals to the compiler to do so. As illustrated in Figure 5-15, there are two ways to use the keyword synchronized. First technique declares class methods synchronized, Figure 5-15(a). If one thread invokes a synchronized method on an object, that object is locked. Another thread invoking this or another synchronized method on that same object will block until the lock is released. Nesting method invocations are handled in the obvious way: when a synchronized method is invoked on an object that is already locked by that same thread, the method returns, but the lock is not released until the outermost synchronized method returns. Second technique designates a statement or a block of code as synchronized. The parenthesized expression must produce an object to lockusually, an object reference. In the simplest case, it could be this reference to the current object, like so
synchronized (this) { /* block of code statements */ }

When the lock is obtained, statement is executed as if it were synchronized method on the locked object. Examples of exclusion synchronization in Java are given in Section 5.3.4.

shared object

obtain lock

release unlock

public class SharedClass { ... public synchronized void method1( ... ) { ... } }

obtain lock release unlock

public class AnyClass { ... public void method2( ... ) { ... synchronized (expression) { statement } ... } shared object }

(a)

(b)

Figure 5-15: Exclusion synchronization in Java: (a) synchronized methods, and (b) synchronized statements.

Ivan Marsic

Rutgers University

206

5.3.3

Cooperation between ThreadsCondition Synchronization

Exclusion synchronization ensures that threads do not step on each others toes, but other than preventing them from colliding, their activities are completely independent. However, sometimes one threads work depends on activities of another thread, so they must cooperate and coordinate. A classic example of cooperation between threads is a Buffer object with methods put() and get(). Producer thread calls put() and consumer thread calls get(). The producer must wait if the buffer is full, and the consumer must wait if it is empty. In both cases, threads wait for a condition to become fulfilled. Condition synchronization includes no assumption that the wait will be brief; threads could wait indefinitely. Condition synchronization (illustrated in Figure 5-16) complements exclusion synchronization. In exclusion synchronization, a thread encountering an occupied shared resource becomes blocked and waits until another thread is finished with using the resource. Conversely, in condition synchronization, a thread encountering an unmet condition cannot continue holding the resource on which condition is checked and just wait until the condition is met. If the tread did so, no other thread would have access to the resource and the condition would never changethe resource must be released, so another thread can affect it. The thread in question might release the resource and periodically return to check it, but this would not be an efficient use of processor cycles. Rather, the thread becomes blocked and does nothing while waiting until the condition changes, at which point it must be explicitly notified of such changes. In the buffer example, a producer thread, t, must first lock the buffer to check if it is full. If it is, t enters the waiting for notification state, see Figure 5-12. But while t is waiting for the condition to change, the buffer must remain unlocked so consumers can empty it by calling get(). Because the waiting thread is blocked and inactive, it needs to be notified when it is ready to go. Every software object in Java has the methods wait() and notify() which makes possible sharing and condition synchronization on every Java object, as explained next. The method wait() is used for suspending threads that are waiting for a condition to change. When t finds the buffer full, it calls wait(), which atomically releases the lock and suspends the thread (see Figure 5-16). Saying that the thread suspension and lock release are atomic means that they happen together, indivisibly from the applications point of view. After some other thread notifies t that the buffer may no longer be full, t regains the lock on the buffer and retests the condition. The standard Java idiom for condition synchronization is the statement:
while (conditionIsNotMet) sharedObject.wait();

Such a wait-loop statement must be inside a synchronized method or block. Any attempt to invoke the wait() or notify() methods from outside the synchronized code will throw IllegalMonitorStateException. The above idiom states that the condition test should always be in a loopnever assume that being woken up means that the condition has been met. The wait loop blocks the calling thread, t, for as long as the condition is not met. By calling wait(), t places itself in the shared objects wait set and releases all its locks on that object. (It is of note that standard Java implements an unordered wait set rather than an ordered wait queue. Real-time specification for JavaRTSJcorrects this somewhat.)

Chapter 5

Design with Patterns

207

thrd1 : Thread loop region

shared_obj : Object

thrd2 : Thread

obtain lock Successful: Checks condition

alt

Condition is met Does the work release lock

[else]

wait()

Atomically releases the lock and waits blocked

region Lock transfer controlled by operating system and hardware transfer lock

obtain lock Successful: Does the work that can affect the wait condition notify() release lock

Figure 5-16: Condition synchronization pattern for concurrent threads. A thread that executes a synchronized method on an object, o, and changes a condition that can affect one or more threads in os wait set must notify those threads. In standard Java, the call o.notify() reactivates one arbitrarily chosen thread, t, in os wait set. The reactivated thread then reevaluates the condition and either proceeds into the critical region or reenters the wait set. The call to o.notifyAll() releases all threads in the os wait set. In standard Java this is the only way to ensure that the highest priority thread is reactivated. This is inefficient, though, because all the threads must attempt access while only one will succeed in acquiring the lock and proceed. The reader might have noticed resemblance between the above mechanism of wait/notify and the publish/subscribe pattern of Section 5.1. In fact, they are equivalent conceptually, but there are some differences due to concurrent nature of condition synchronization.

5.3.4

Concurrent Programming Example

Concurrent Home Access

The following example illustrates cooperation between threads. Example 4.1

In our case-study, Figure 1-12 shows lock controls both on front and backyard doors. Suppose two different tenants arrive (almost) simultaneously at the different doors and attempt the access, see Figure 5-17. The single-threaded system designed in Section 2.7 would process them one-by-one, which may cause the second user to wait considerable amount of time. A user unfamiliar with the system intricacies may perceive this as a serious glitch. As shown in Figure 5-17, the processor is idle most of the time, such as between individual keystrokes or while the user tries to recall the exact

Ivan Marsic

Rutgers University

208

User 1

Arrival

Service

Time
Arrival Waiting Service

User 2
Total interaction time for both users Average interaction time

Figure 5-17: Single-threaded, sequential servicing of users in Example 4.1.

password after an unsuccessful attempt. Meanwhile, the second user is needlessly waiting. To improve the user experience, let us design a multithreaded solution. The solution is given next.

The first-round implementation in Section 2.7, considered the system with a single door lock. We have not yet tackled the architectural issue of running a centralized or a distributed system. In the former case, the main computer runs the system and at the locks we have only embedded processors. We could add an extra serial port, daisy-chained with the other one, and the control would remain as in Section 2.7. In the latter case of a distributed system, each lock would have a proximal embedded computer. The embedded computers would communicate mutually or with the main computer using a local area network. The main computer may even not be necessary, and the embedded processors could coordinate in a peer-to-peer mode. Assume for now that we implement the centralized PC solution with multiple serial ports. We also assume a single photosensor and a single light bulb, for the sake of simplicity. The first question to answer is, how many threads we need and which objects should be turned into threads? Generally, it is not a good idea to add threads indiscriminately, because threads consume system resources, such as computing cycles and memory space. It may appear attractive to attach a thread to each object that operates physical devices, such as LockCtrl and LightCtrl, but is this the right approach? On the other hand, there are only two users (interacting with the two locks), so perhaps two threads would suffice? Let us roll back, see why we consider introducing threads in the first place. The reason is to improve the user experience, so two users at two different doors can access the home simultaneously, without waiting. Two completely independent threads would work, which would require duplicating all the resources, but this may be wasteful. Here is the list of resources they could share:

KeyStorage, used to lookup the valid keys Serial port(s), to communicate with the devices System state, such as the device status or current count of unsuccessful trials

Sharing KeyStorage seems reasonablehere it is just looked up, not modified. The serial port can also be shared because the communication follows a well-defined RS-232 protocol. However, sharing the system state needs to be carefully examined. Sharing the current count of

Chapter 5

Design with Patterns

209

unsuccessful trials seems to make no sensethere must be two counters, each counting accesses for its corresponding door. There are several observations that guide our design. From the system sequence diagram of Figure 2-5(a), we can observe that the system juggles two distinct tasks: user interaction and internal processing which includes controlling the devices. There are two copies (for the two doors) of each task, which should be able to run in parallel. The natural point of separation between the two tasks is the Controller object, Figure 2-17, which is the entry point of the domain layer of the system. The Controller is a natural candidate for a thread object, so two internal processing tasks can run in parallel, possibly sharing some resources. The threaded controller class, ControllerThd, is defined below. I assume that all objects operating the devices (LockCtrl, LightCtrl, etc.) can be shared as long as the method which writes to the serial port is synchronized. LockCtrl must also know which lock (front or backyard) it currently operates.

Listing 5-5: Concurrent version of the main class for home access control. Compare to Listing 2-1.
import import import import javax.comm.*; java.io.IOException; java.io.InputStream; java.util.TooManyListenersException;

public class HomeAccessControlSystem_2x extends Thread implements SerialPortEventListener { protected ControllerThd contrlFront_; // front door controller protected ControllerThd contrlBack_; // back door controller protected InputStream inputStream_; // from the serial port protected StringBuffer keyFront_ = new StringBuffer(); protected StringBuffer keyBack_ = new StringBuffer(); public static final long keyCodeLen_ = 4; // key code of 4 chars public HomeAccessControlSystem_2x( KeyStorage ks, SerialPort ctrlPort ) { try { inputStream_ = ctrlPort.getInputStream(); } catch (IOException e) { e.printStackTrace(); } LockCtrl lkc = new LockCtrl(ctrlPort); LightCtrl lic = new LightCtrl(ctrlPort); PhotoObsrv sns = new PhotoObsrv(ctrlPort); AlarmCtrl ac = new AlarmCtrl(ctrlPort); contrlFront_ = new ControllerThd( new KeyChecker(ks), lkc, lic, sns, ac, keyFront_ ); contrlBack_ = new ControllerThd( new KeyChecker(ks), lkc, lic, sns, ac, keyBack_ ); try { ctrlPort.addEventListener(this); } catch (TooManyListenersException e) {

Ivan Marsic

Rutgers University

210

e.printStackTrace(); // limited to one listener per port } start(); // start the serial-port reader thread } /** The first argument is the handle (filename, IP address, ...) * of the database of valid keys. * The second arg is optional and, if present, names * the serial port. */ public static void main(String[] args) { ... // same as in Listing 2-1 above } /** Thread method; does nothing, just waits to be interrupted * by input from the serial port. */ public void run() { while (true) { try { Thread.sleep(100); } catch (InterruptedException e) { /* do nothing */ } } } /** Serial port event handler. * Assume that the characters are sent one by one, as typed in. * Every character is preceded by a lock identifier (front/back). */ public void serialEvent(SerialPortEvent evt) { if (evt.getEventType() == SerialPortEvent.DATA_AVAILABLE) { byte[] readBuffer = new byte[5]; // just in case, 5 chars try { while (inputStream_.available() > 0) { int numBytes = inputStream_.read(readBuffer); // could chk if numBytes == 2 (char + lockId) ... } } catch (IOException e) { e.printStackTrace(); } // Append the new char to a user key, and if the key // is complete, awaken the corresponding Controller thread if (inputStream_[0] == 'f') { // from the front door // If this key is already full, ignore the new chars if (keyFront_.length() < keyCodeLen_) { synchronized (keyFront_) { // CRITICAL REGION keyFront_.append(new String(readBuffer, 1,1)); // If the key just got completed, // signal the condition to others if (keyFront_.length() >= keyCodeLen_) { // awaken the Front door Controller keyFront_.notify(); //only 1 thrd waiting } } // END OF THE CRITICAL REGION } } else if (inputStream_[0] == 'b') { // from back door if (keyBack_.length() < keyCodeLen_) { synchronized (keyBack_) { // CRITICAL REGION keyBack_.append(new String(readBuffer, 1, 1));

Chapter 5

Design with Patterns

211

if (keyBack_.length() >= keyCodeLen_) { // awaken the Back door Controller keyBack_.notify(); } } // END OF THE CRITICAL REGION } // else, exception ?! } } }

Each Controller object is a thread, and it synchronizes with HomeAccessControlSystem_2x via the corresponding user key. In the above method serialEvent(), the port reader thread fills in the key code until completed; thereafter, it ignores the new keys until the corresponding ControllerThd processes the key and resets it in its run() method, shown below. The reader should observe the reuse of a StringBuffer to repeatedly build strings, which works here, but in a general case many subtleties of Java StringBuffers should be considered.

Listing 5-6: Concurrent version of the Controller class. Compare to Listing 2-2.
import javax.comm.*; public class ControllerThd implements Runnable { protected KeyChecker checker_; protected LockCtrl lockCtrl_; protected LightCtrl lightCtrl_; protected PhotoObsrv sensor_; protected AlarmCtrl alarmCtrl_; protected StringBuffer key_; public static final long maxNumOfTrials_ = 3; public static final long trialPeriod_ = 600000; // msec [= 10 min] protected long numOfTrials_ = 0; public ControllerThd( KeyChecker kc, LockCtrl lkc, LightCtrl lic, PhotoObsrv sns, AlarmCtrl ac, StringBuffer key ) { checker_ = kc; lockCtrl_ = lkc; alarmCtrl_ = ac; lightCtrl_ = lic; sensor_ = sns; key_ = key; Thread t = new Thread(this, getName()); t.start(); } public void run() { while(true) { // runs forever synchronized (key_) { // CRITICAL REGION // wait for the key to be completely typed in while(key_.length() < HomeAccessControlSystem_2x.keyCodeLen_) { try { key_.wait(); } catch(InterruptedException e) { throw new RuntimeException(e);

Ivan Marsic

Rutgers University

212

} } } // END OF THE CRITICAL REGION // Got the key, check its validity: // First duplicate the key buffer, then release old copy Key user_key = new Key(new String(key_)); key_.setLength(0); // delete code, so new can be entered checker_.checkKey(user_key); // assume Publish-Subs. vers. } } }

The reader should observe the thread coordination in the above code. We do not want the Controller to grab a half-ready Key and pass it to the Checker for validation. The Controller will do so only when notify() is invoked. Once it is done with the key, the Controller resets it to allow the reader to fill it again. You may wonder how is it that in ControllerThd.run() we obtain the lock and then loop until the key is completely typed inwould this not exclude the port reader thread from the access to the Key object, so the key would never be completed?! Recall that wait() atomically releases the lock and suspends the ControllerThd thread, leaving Key accessible to the port reader thread. It is interesting to consider the last three lines of code in ControllerThd.run(). Copying a StringBuffer to a new String is a thread-safe operation; so is setting the length of a StringBuffer. However, although each of these methods acquires the lock, the lock is released in between and another thread may grab the key object and do something bad to it. In our case this will not happen, because HomeAccessControlSystem_2x.serialEvent() checks the length of the key before modifying it, but generally, this is a concern. Figure 5-18 summarizes the benefit achieved by a multithreaded solution. Notice that there still may be micro periods of waiting for both users and servicing the user who arrived first may take longer than in a single-threaded solution. However, the average service time per user is much shorter, close to the single-user average service time.

Hazards and Performance Penalties

Ideally, we would like that the processor is never idle while there is a task waiting for execution. As seen in Figure 5-18(b), even with threads the processor may be idle while there are users who are waiting for service. The question of granularity of the shared resource. Or stated differently, the key issue is how to minimize the length (i.e., processing time) of the critical region. Solution: Try to narrow down the critical region by lock splitting or using finer-grain locks. http://www.cs.panam.edu/~meng/Course/CS6334/Note/master/node49.html http://searchstorage.techtarget.com/sDefinition/0,,sid5_gci871100,00.html http://en.wikipedia.org/wiki/Thread_(computer_programming)

Chapter 5

Design with Patterns

213

User 1

Arrival

Service

Time

(a)
Arrival Waiting

Service

User 2
Total interaction time for both users Average interaction time

User 1

Arrival

Service

Time

(b)
Arrival

Waiting Service

User 2
Total interaction time for both users Average interaction time

Figure 5-18: Benefit of a multithreaded solution. (a) Sequential servicing, copied from Figure 5-17. (b) Parallel servicing by two threads.

Control of access to shared resources itself can introduce problems, e.g., it can cause deadlock.

5.4 Broker and Distributed Computing

If computers get too powerful, we can organize them into a committeethat will do them in. Bradleys Bromide

Let us assume that in our case-study example of home access control the tenants want to remotely download the list of recent accesses. This requires network communication. The most basic network programming uses network sockets, which can call for considerable programming skills (see Appendix B for a brief review). To simplify distributed computing, a set of software techniques have been developed. These generally go under the name of network middleware. When both client and server objects reside in the same memory space, the communication is carried out by simple method calls on the server object (see Figure 1-22). If the objects reside in different memory spaces or even on different machines, they need to implement the code for interprocess communication, such as opening network connections, sending messages across the network, and dealing with many other aspects of network communication protocols. This significantly increases the complexity of objects. Even worse, in addition to its business logic, objects obtain responsibility for communication logic which is extraneous to their main function.

Ivan Marsic

Rutgers University

214

Unmarshaling Marshaling

Middleware

Network

Figure 5-19: Client object invokes a method on a server object. If the message sending becomes too complex, introducing middleware offloads the communication intricacies off the software objects. (Compare with Figure 1-22.) Employing middleware helps to delegate this complexity away out of the objects, see Figure 5-19. A real world example of middleware is the post serviceit deals with the intricacies of delivering letters/packages to arbitrary distances. Another example is the use of different metric systems, currencies, spoken languages, etc., in which case the functionality for conversion between the systems is offloaded to middleware services. Middleware is a good software engineering practice that should be applied any time the communication between objects becomes complex and starts rivaling the objects business logic in terms of the implementation code size.

Middleware is a collection of objects that offer a set of services related to object communication, so that extraneous functionality is offloaded to the middleware. In general, middleware is software used to make diverse applications work together smoothly. The process of deriving middleware is illustrated in Figure 5-20. We start by introducing the proxies for both communicating objects. (The Proxy pattern is described in Section 5.2.2.) The proxy object B of B acts so to provide an illusion for A that it is directly communicating with B. The same is provided to B by A. Having the proxy objects keeps simple the original objects, because the proxies provide them with an illusion that nothing changed from the original case, where they communicated directly with each other, as in Figure 5-20(a). In other words, proxies provide location transparency for the objectsobjects remain (almost) the same no matter whether they

Chapter 5

Design with Patterns

215

(a)

Object Object A A

Object Object B B

Middleware

(b)

Object Object A A

Object Object B' B'

Object Object A' A'

Object Object B B

Figure 5-20: Middleware design. Objects A and B are the proxies of A and B, respectively. reside in the same address space or in different address spaces / machines. Objects A' and B' comprise the network middleware. Because it is not likely that we will develop middleware for only two specific objects communicating, further division of responsibilities results in the Broker pattern.

Ivan Marsic

Rutgers University

216

Middleware

Broker component Bclient Bclient Bserver Bserver C' C' S S

(a)

C C

S' S'

Service Service

Service Service

Broker

(b)

Knowing Responsibilities: Registry of name-to-reference mappings Doing Responsibilities: Maintains the registry and provides lookup Instantiates proxies Network transport of request and result back

Client + callServer() # useBrokerAPI() MiddlewareService + + + # #

Server initialize() mainEventLoop() request() registerService() useBrokerAPI()

(c)
server proxy Stub + + # # request() forwardResponse() marshal() unmarshal() + + + + # #

Broker mainEventLoop() registerService() forwardRequest() forwardResponse() findServer() findClient() client proxy Skeleton + forwardRequest() # marshal() # unmarshal()

Figure 5-21: (a) The Broker component of middleware represents the intersection of common proxy functions, along with middleware services. (b) Brokers employee card. (c) The Broker pattern class diagram. The server proxy, called Stub, resides on the same host as the client and the client proxy, called Skeleton, resides on the same host as the server.

5.4.1

Broker Pattern

The Broker pattern is an architectural pattern used to structure distributed software systems with components that interact by remote method calls, see Figure 5-21. The proxies are responsible only for the functions specific to individual objects for which they act as substitutes. In a distributed system the functions that are common to all or most of the proxies are delegated to the Broker component, Figure 5-21(b). Figure 5-21(c) shows the objects constituting the Broker pattern and their relationships. The proxies act as representatives of their corresponding objects in

Chapter 5

Design with Patterns

217

: Client callServer() request()

: Stub

: Broker

: Skeleton

: Server

marshal()

forwardRequest()

findServer()

forwardRequest()

unmarshal() request() response marshal()

forwardResponse() findClient() forwardResponse() unmarshal() response

Figure 5-22: Sequence diagram for a client call to the server (remote method invocation). the foreign address space and contain all the network-related code. The broker component is responsible for coordinating communication and providing links to various middleware services. Although Broker is shown as a single class in Figure 5-21(c), actual brokers consist of many classes are provide many services. To use a remote object, a client first finds the object through the Broker, which returns a proxy object or Stub. As far as the client is concerned, the Stub appears and works like any other local object because they both implement the same interface. But, in reality it only arranges the method call and associated parameters into a stream of bytes using the method marshal(). Figure 5-22 shows the sequence diagram for remote method invocation (also called remote procedure call RPC) via a Broker. The Stub marshals the method call into a stream of bytes and invokes the Broker, which forwards the byte stream to the clients proxy, Skeleton, at the remote host. Upon receiving the byte stream, the Skeleton rearranges this stream into the original method call and associated parameters, using the method unmarshal(), and invokes this method on the server which contains the actual implementation. Finally, the server performs the requested operation and sends back the return value(s), if any. The Broker pattern has been proven effective tool in distributed computing, because it leads to greater flexibility, maintainability, and adaptability of the resulting system. By introducing new components and delegating responsibility for communication intricacies, the system becomes potentially distributable and scalable. Java Remote Method Invocation (RMI), which is presented next, is an example of elaborating and implementing the Broker pattern.

Ivan Marsic

Rutgers University

218

5.4.2

Java Remote Method Invocation (RMI)

The above analysis indicates that the Broker component is common to all remotely communicating objects, so it needs to be implemented only once. The proxies are object-specific and need to be implemented for every new object. Fortunately, the process of implementing the proxy objects can be made automatic. It is important to observe that the original object shares the same interface with its Stub and Skeleton (if the object acts as a client, as well). Given the objects interface, there are tools to automatically generate source code for proxy objects. In the general case, the interface is defined in an Interface Definition Language (IDL). Java RMI uses plain Java for interface definition, as well. The basic steps for using RMI are: 1. Define the server object interface 2. Define a class that implements this interface 3. Create the server process 4. Create the client process Going back to our case-study example of home access control, now I will show how a tenant could remotely connect and download the list of recent accesses.

Step 1: Define the server object interface

The server object will be running on the home computer and currently offers a single method which returns the list of home accesses for the specified time interval:

Listing 5-7: The Informant remote server object interface.

/* file Informant.java */ import java.rmi.Remote; import java.rmi.RemoteException; import java.util.Vector; public interface Informant extends Remote { public Vector getAccessHistory(long fromTime, long toTime) throws RemoteException; }

This interface represents a contract between the server and its clients. Our interface must extend java.rmi.Remote which is a tagging interface that contains no methods. Any parameters of the methods of our interface, such as the return type Vector in our case, must be serializable, i.e., implement java.io.Serializable. In the general case, an IDL compiler would generate a Stub and Skeleton files for the Informant interface. With Java RMI, we just use the Java compiler, javac:
% javac Informant.java

Chapter 5

Design with Patterns

219

Remote

UnicastRemoteObject

Client

Informant + getAccessHistory()

InformantImpl_Stub RemoteRef + getAccessHistory()

InformantImpl + getAccessHistory()

Figure 5-23: Class diagram for the Java RMI example. See text for details.

Step 2: Define a class that implements this interface

The implementation class must extend class java.rmi.server.RemoteObject or one of its subclasses. In practice, most implementations extend the subclass java.rmi.server.UnicastRemoteObject, because this class supports point-to-point communication using the TCP protocol. The class diagram for this example is shown in Figure 5-23. The implementation class must implement the interface methods and a constructor (even if it has an empty body). I adopt the common convention of adding Impl onto the name of our interface to form the implementation class.

Listing 5-8: The class InformantImpl implements the actual remote server object.
/* file InformantImpl.java (Informant server implementation) */ import java.rmi.RemoteException; import java.rmi.server.UnicastRemoteObject; import java.util.Vector; public class InformantImpl extends UnicastRemoteObject implements Informant { protected Vector accessHistory_ = new Vector(); /** Constructor; currently empty. */ public InformantImpl() throws RemoteException { } /** Records all the home access attempts. * Called from another class, e.g., from KeyChecker, Listing 2-2 * @param access Contains the entered key, timestamp, etc. */ public void recordAccess(String access) { accessHistory_.add(access); } /** Implements the "Informant" interface. */ public Vector getAccessHistory(long fromTime, long toTime) throws RemoteException { Vector result = new Vector(); // Extract from accessHistory_ accesses in the // interval [fromTime, toTime] into "result"

Ivan Marsic

Rutgers University

220

return result; } }

Here, we first use the Java compiler, javac, then the RMI compiler, rmic:
% javac InformantImpl.java % rmic v1.2 InformantImpl

The first statement compiles the Java file and the second one generates the stub and skeleton proxies, called InformantImpl_Stub.class and InformantImpl_Skel.class, respectively. It is noteworthy, although perhaps it might appear strange, that the RMI compiler operates on a .class file, rather than on a source file. In JDK version 1.2 or higher (Java 2), only the stub proxy is used; the skeleton is incorporated into the server itself so that there are no separate entities as skeletons. Server programs now communicate directly with the remote reference layer. This is why the command line option -v1.2 should be employed (that is, if you are working with JDK 1.2 or higher), so that only the stub file is generated. As shown in Figure 5-23, the stub is associated with a RemoteRef, which is a class in the RMI Broker that represents the handle for a remote object. The stub uses a remote reference to carry out a remote method invocation to a remote object via the Broker. It is instructive to look inside the InformantImpl_Stub.java, which is obtained if the RMI compiler is run with the option -keep. Here is the stub file (the server proxy resides on client host):

Listing 5-9: Proxy classes (Stub and Skeleton) are automatically generated by the Java rmic compiler from the Informant interface (Listing 5-7).
// Stub class generated by rmic, do not edit. // Contents subject to change without notice.
Marshaling

1 public final class InformantImpl_Stub 2 extends java.rmi.server.RemoteStub 3 implements Informant, java.rmi.Remote 4 { 5 private static final long serialVersionUID = 2; 6 7 private static java.lang.reflect.Method $method_getAccessHistory_0; 8 9 static { 10 try { 11 $method_getAccessHistory_0 = Informant.class.getMethod("getAccessHistory", new java.lang.Class[] {long.class, long.class}); 12 } catch (java.lang.NoSuchMethodException e) { 13 throw new java.lang.NoSuchMethodError( 14 "stub class initialization failed"); 15 } 16 } 17 18 // constructors 19 public InformantImpl_Stub(java.rmi.server.RemoteRef ref) { 20 super(ref); 21 } 22

Chapter 5

Design with Patterns

221

23 // methods from remote interfaces 24 25 // implementation of getAccessHistory(long, long) 26 public java.util.Vector getAccessHistory(long $param_long_1, long $param_long_2) 27 throws java.rmi.RemoteException 28 { 29 try { 30 Object $result = ref.invoke(this, $method_getAccessHistory_0, new java.lang.Object[] {new java.lang.Long($param_long_1), new java.lang.Long($param_long_2)}, 7208692514216622197L); 31 return ((java.util.Vector) $result); 32 } catch (java.lang.RuntimeException e) { 33 throw e; 34 } catch (java.rmi.RemoteException e) { 35 throw e; 36 } catch (java.lang.Exception e) { 37 throw new java.rmi.UnexpectedException("undeclared checked exception", e); 38 } 39 } 40 }

The code description is as follows: Line 2: shows that our stub extends the RemoteStub class, which is the common superclass to client stubs and provides a wide range of remote reference semantics, similar to the broker services in Figure 5-21(a). Lines 715: perform part of the marshaling process of the getAccessHistory() method invocation. Computational reflection is employed, which is described in Section 7.3. Lines 1921: pass the remote servers reference to the RemoteStub superclass. Line 26: starts the definition of the stubs version of the getAccessHistory() method. Line 30: sends the marshaled arguments to the server and makes the actual call on the remote object. It also gets the result back. Line 31: returns the result to the client. The reader should be aware that, in terms of how much of the Broker component is revealed in a stub code, this is only a tip of the iceberg. The Broker component, also known as Object Request Broker (ORB), can provide very complex functionality and comprise many software objects.

Step 3: Create the server process

The server process instantiates object(s) of the above implementation class, which accept remote requests. The first problem is, how does a client get handle of such an object, so to be able to invoke a method on it? The solution is for the server to register the implementation objects with a naming service known as registry. A naming registry is like a telephone directory. The RMI Registry is a simple name repository which acts as a central management point for Java RMI. The registry must be run before the server and client processes using the following command line:

Ivan Marsic

Rutgers University

222

% rmiregistry

It can run on any host, including the servers or clients hosts, and there can be several RMI registries running at the same time. (Note: The RMI Registry is an RMI server itself.) For every server object, the registry contains a mapping between the well-known objects name and its reference (usually a globally unique sequence of characters). The process of registration is called binding. The client object can, thus, get handle of a server object by looking up its name in the registry. The lookup is performed by supplying a URL with protocol rmi: rmi://host_name:port_number/object_name where host_name is the name or IP address of the host on which the RMI registry is running, port_number is the port number of the RMI registry, and object_name is the name bound to the server implementation object. If the host name is not provided, the default is assumed as localhost. The default port number of RMI registry is 1099, although this can be changed as desired. The server object, on the other hand, listens to a port on the server machine. This port is usually an anonymous port that is chosen at runtime by the JVM or the underlying operating system. Or, you can request the server to listen on a specific port on the server machine. I will use the class HomeAccessControlSystem, defined in Listing 2-1, Section 2.7, as the main server class. The class remains the same, except for several modifications:

Listing 5-10: Refactored HomeAccessControlSystem class (from Listing 2-1) to instantiate remote server objects of type Informant.
1 import java.rmi.Naming; 2 3 public class HomeAccessControlSystem extends Thread 4 implements SerialPortEventListener { 5 ... 6 private static final String RMI_REGISTRY_HOST = "localhost"; 7 8 public static void main(String[] args) throws Exception { 9 ... 10 InformantImpl temp = new InformantImpl(); 11 String rmiObjectName = 12 "rmi://" + RMI_REGISTRY_HOST + "/Informant"; 13 Naming.rebind(rmiObjectName, temp); 14 System.out.println("Binding complete..."); 15 ... 16 } ... }

The code description is as follows: Lines 35: The old HomeAccessControlSystem class as defined in Section 2.7. Line 6: For simplicitys sake, I use localhost as the host name, which could be omitted because it is default. Line 8: The main() method now throws Exception to account for possible RMI-related exceptions thrown by Naming.rebind(). Line 10: Creates an instance object of the server implementation class.

Chapter 5

Design with Patterns

223

Lines 1112: Creates the string URL which includes the objects name, to be bound with its remote reference. Line 13: Binds the objects name to the remote reference at the RMI naming registry. Line 14: Displays a message for our information, to know when the binding is completed. The server is, after compilation, run on the computer located at home by invoking the Java interpreter on the command line:
% java HomeAccessControlSystem

If Java 2 is used, the skeleton is not necessary; otherwise, the skeleton class, InformantImpl_Skel.class, must be located on the servers host because, although not explicitly used by the server, the skeleton will be invoked by Java runtime.

Step 4: Create the client process

The client requests services from the server object. Because the client has no idea on which machine and to which port the server is listening, it looks up the RMI naming registry. What it gets back is a stub object that knows all these, but to the client the stub appears to behave same as the actual server object. The client code is as follows:

Listing 5-11: Client class InformantClient invokes services on a remote Informant object.
1 import java.rmi.Naming; 2 3 public class InformantClient { 4 private static final String RMI_REGISTRY_HOST = " ... "; 5 6 public static void main(String[] args) { 7 try { 8 Informant grass = (Informant) Naming.lookup( 9 "rmi://" + RMI_REGISTRY_HOST + "/Informant" 10 ); 11 Vector accessHistory = 12 grass.getAccessHistory(fromTime, toTime); 13 14 System.out.println("The retrieved history follows:"); 15 for (Iterator i = accessHistory; i.hasNext(); ) { 16 String record = (String) i.next(); 17 System.out.println(record); 18 } 19 } catch (ConnectException conEx) { 20 System.err.println("Unable to connect to server!"); 21 System.exit(1); 22 } catch (Exception ex) { 23 ex.printStackTrace(); 24 System.exit(1); 25 } 26 ... 27 } ... }

Ivan Marsic

Rutgers University

224

The code description is as follows: Line 4: Specifies the host name on which the RMI naming registry is running. Line 8: Looks up the RMI naming registry to get handle of the server object. Because the lookup returns a java.rmi.Remote reference, this reference must be typecast into an Informant reference (not InformantImpl reference). Lines 1112: Invoke the service method on the stub, which in turn invokes this method on the remote server object. The result is returned as a java.util.Vector object named accessHistory. Lines 1418: Display the retrieved history list. Lines 1925: Handle possible RMI-related exceptions. The client would be run from a remote machine, say from the tenants notebook or a PDA. The InformantImpl_Stub.class file must be located on the clients host because, although not explicitly used by the client, a reference to it will be given to the client by Java runtime. A security-conscious practice is to make the stub files accessible on a website for download. Then, you set the java.rmi.server.codebase property equal to the websites URL, in the application which creates the server object (in our example above, this is HomeAccessControlSystem ). The stubs will be downloaded over the Web, on demand.

The reader should notice that distributed object computing is relatively easy using Java RMI. The developer is required to do just slightly more work, essentially to bind the object with the RMI registry on the server side and to obtain a reference to it on the client side. All the complexity associated with network programming is hidden by the Java RMI tools.
HOW TRANSPARENT OBJECT DISTRIBUTION?

The reader who experiments with Java RMI, see e.g., Problem 5.13, and tries to implement the same with plain network sockets (see Appendix B), will appreciate how easy it is to work with distributed objects. My recollection from using some CORBA object request brokers was that some provided even greater transparency than Java RMI. Although this certainly is an advantage, there are perils of making object distribution so transparent that it becomes too easy.
The problem is that people tended to forget that there is a network between distributed objects and built applications that relied on fine-grained communication across the network. Too many round-trip communications led to poor performance and reputation problems for CORBA. An interesting discussion of object distribution issues is available in [Waldo et al., 1994] from the same developers who authored Java RMI [Wollrath et al., 1996].

Chapter 5

Design with Patterns

225

5.5 Information Security

Information security is a nonfunctional property of the system, it is an emergent property. Owing to different types of information use, there are two main security disciplines. Communication security is concerned with protecting information when it is being transported between different systems. Computer security is related to protecting information within a single system, where it can be stored, accessed, and processed. Although both disciplines must work in accord to successfully protect information, information transport faces greater challenges and so communication security has received greater attention. Accordingly, this review is mainly concerned with communication security. Notice that both communication- and computer security must be complemented with physical (building) security as well as personnel security. Security should be thought of as a chain that is as strong as its weakest link. The main objectives of information security are:

Confidentiality: ensuring that information is not disclosed or revealed to unauthorized persons Integrity: ensuring consistency of data, in particular, preventing unauthorized creation, modification, or destruction of data Availability: ensuring that legitimate users are not unduly denied access to resources, including information resources, computing resources, and communication resources Authorized use: ensuring that resources are not used by unauthorized persons or in unauthorized ways

To achieve these objectives, we institute various safeguards, such as concealing (encryption) confidential information so that its meaning is hidden from spying eyes; and key management which involves secure distribution and handling of the keys used for encryption. Usually, the complexity of one is inversely proportional to that of the otherwe can afford relatively simple encryption algorithm with a sophisticated key management method.

Ivan Marsic
Padlock and shared key copy

Rutgers University

226

Content

Shared key copy

Message

Sender
Sender needs: receive securely a copy of the shared key positively identify the message receiver

Intermediary
Threats posed by intruder/adversary: forge the key and view the content damage/substitute the padlock damage/destroy the message observe characteristics of messages (statistical and/or metric properties)

Receiver
Receiver needs: receive securely a shared key copy positively identify the message sender detect any tampering with messages

Figure 5-24: Communication security problem: Sender needs to transport a confidential document to Receiver over an untrusted intermediary. Figure 5-24 illustrates the problem of transmitting a confidential message by analogy with transporting a physical document via untrusted carrier. The figure also lists the security needs of the communicating parties and the potential threats posed by intruders. The sender secures the briefcase, and then sends it on. The receiver must use a correct key in order to unlock the briefcase and read the document. Analogously, a sending computer encrypts the original data using an encryption algorithm to make it unintelligible to any intruder. The data in the original form is known as plaintext or cleartext. The encrypted message is known as ciphertext. Without a corresponding decoder, the transmitted information (ciphertext) would remain scrambled and be unusable. The receiving computer must regenerate the original plaintext from the ciphertext with the correct decryption algorithm in order to read it. This pair of data transformations, encryption and decryption, together forms a cryptosystem. There are two basic types of cryptosystems: (i) symmetric systems, where both parties use the same (secret) key in encryption and decryption transformations; and, (ii) public-key systems, also known as asymmetric systems, where the parties use two related keys, one of which is secret and the other one can be publicly disclosed. I first review the logistics of how the two types of cryptosystems work, while leaving the details of encryption algorithms for the next section.

Chapter 5
Senders padlock

Design with Patterns

227
Receivers padlock

1. Sender secures the briefcase

with his/her padlock and sends

Sender

2. Receiver additionally secures

the briefcase with his/her padlock and returns

Receiver

3. Sender removes his/her

padlock and sends again

4. Receiver removes his/her

padlock to access the content

Figure 5-25: Secure transmission via untrustworthy carrier. Note that both sender and receiver keep their own keys with them all the timethe keys are never exchanged.

5.5.1

Symmetric and Public-Key Cryptosystems

In symmetric cryptosystems, both parties use the same key in encryption and decryption transformations. The key must remain secret and this, of course, implies trust between the two parties. This is how cryptography traditionally works and prior to the late 1970s, these were the only algorithms available. The system works as illustrated in Figure 5-24. In order to ensure the secrecy of the shared key, the parties need to meet prior to communication. In this case, the fact that only the parties involved know the secret key implicitly identifies one to the other. Using encryption involves two basic steps: encoding a message, and decoding it again. More formally, a code takes a message M and produces a coded form f(M). Decoding the message requires an inverse function f 1 , such that f 1 ( f ( M ) ) = M. For most codes, anyone who knows how to perform the first step also knows how to perform the second, and it would be unthinkable to release to the adversary the method whereby a message can be turned into code. Merely by undoing the encoding procedures, the adversary would be able to break all subsequent coded messages. In the 1970s Ralph Merkle, Whitfield Diffie, and Martin Hellman realized that this need not be so. The weasel word above is merely. Suppose that the encoding procedure is very hard to undo. Then it does no harm to release its details. This led them to the idea of a trapdoor function. We call f a trapdoor function if f is easy to compute, but f 1 is very hard, indeed impossible for practical purposes. A trapdoor function in this sense is not a very practical code, because the legitimate user finds it just as hard to decode the message as the adversary does. The final twist is

Ivan Marsic

Rutgers University

228

Public key

Receiver distributes his/her padlock (unlocked) to sender ahead of time, but keeps the key

Private key

Receivers padlock (unlocked)

Receiver

Receivers key

Sender uses the receivers padlock to secure the briefcase and sends

Sender
Receiver removes his/her padlock to access the content

Figure 5-26: Public-key cryptosystem simplifies the procedure from Figure 5-25. to define f in such a way that a single extra piece of information makes the computation of f 1 easy. This is the only bit of information that must be kept secret. This alternative approach is known as public-key cryptosystems. To understand how it works, it is helpful to examine the analogy illustrated in Figure 5-25. The process has three steps. In the first step, the sender secures the briefcase with his or her padlock and sends. Second, upon receiving the briefcase, the receiver secures it additionally with their own padlock and returns. Notice that the briefcase is now doubly secured. Finally, the sender removes his padlock and re-sends. Hence, sender manages to send a confidential document to the receiver without needing the receivers key or surrendering his or her own key. There is an inefficiency of sending the briefcase back and forth, which can be avoided as illustrated in Figure 5-26. Here we can skip steps 1 and 2 if the receiver distributed his/her padlock (unlocked, of course!) ahead of time. When the sender needs to send a document, i.e., message, he/she simply uses the receivers padlock to secure the briefcase and sends. Notice that, once the briefcase is secured, nobody else but receiver can open it, not even the sender. Next I describe how these concepts can be implemented for electronic messages.

5.5.2

Cryptographic Algorithms

Encryption has three aims: keeping data confidential; authenticating who sends data; and, ensuring data has not been tampered with. All cryptographic algorithms involve substituting one thing for another, which means taking a piece of plaintext and then computing and substituting the corresponding ciphertext to create the encrypted message.

Chapter 5

Design with Patterns

229

Symmetric Cryptography
The Advanced Encryption Standard has a fixed block size of 128 bits and a key size of 128, 192, and 256 bits.

Public-Key Cryptography
As stated above, f is a trapdoor function if f is easy to compute, but f 1 is very hard or impossible for practical purposes. An example of such difficulty is factorizing a given number n into prime numbers. An encryption algorithm that depends on this was invented by Ron Rivest, Adi Shamir, and Leonard Adelman (RSA system) in 1978. Another example algorithm, designed by Taher El Gamal in 1984, depends on the difficulty of the discrete logarithm problem. In the RSA system, the receiver does as follows: 1. Randomly select two large prime numbers p and q, which always must be kept secret. 2. Select an integer number E, known as the public exponent, such that (p 1) and E have no common divisors, and (q 1) and E have no common divisors. 3. Determine the product n = pq, known as public modulus. 4. Determine the private exponent, D, such that (ED 1) is exactly divisible by both (p 1) and (q 1). In other words, given E, we choose D such that the integer remainder when ED is divided by (p 1)(q 1) is 1. 5. Release publicly the public key, which is the pair of numbers n and E, K + = (n, E). Keep secret the private key, K = (n, D). Because a digital message is a sequence of digits, break it into blocks which, when considered as numbers, are each less than n. Then it is enough to encode block by block. Encryption works so that the sender substitutes each plaintext block B by the ciphertext C = BE % n, where % symbolizes the modulus operation. (The modulus of two integer numbers x and y, denoted as x % y, is the integer remainder when x is divided by y.) Then the encrypted message C (ciphertext) is transmitted. To decode, the receiver uses the decoding key D, to compute B = CD % n, that is, to obtain the plaintext B from the ciphertext C. Example 4.2 RSA cryptographic system

As a simple example of RSA, suppose the receiver chooses p = 5 and q = 7. Obviously, these are too small numbers to provide any security, but they make the presentation manageable. Next, the receiver chooses E = 5, because 5 and (5 1)(7 1) have no common factors. Also, n = pq = 35. Finally, the ED receiver chooses D = 29, because ( p1)(11) = 5291 = 144 = 6 , i.e., they are exactly divisible. The q 46 24 receivers public key is K + = (n, E) = (35, 5), which is made public. The private key K = (n, D) = (35, 29) is kept secret. Now, suppose that the sender wants to send the plaintext hello world. The following table shows the encoding of hello. I assign to letters a numeric representation, so that a=1, b=2, , y=25, and z=26, and I assume that block B is one letter long. In an actual implementation, letters are represented as binary numbers, and the blocks B are not necessarily aligned with letters, so that plaintext l will not always be represented as ciphertext 12.

Ivan Marsic

Rutgers University

230

Plaintext letter h e l l o

Plaintext numeric representation 8 5 12 12 15

BE 85 = 32768 55 = 3125 125 = 248832 248832 155 = 759375

Ciphertext BE % n 85 % 35 = 8 55 % 35 = 10 125 % 35 = 17 17 155 % 35 = 15

The sender transmits this ciphertext to the receiver: 8, 10, 17, 17, 15. Upon the receipt, the receiver decrypts the message as shown in the following table. Ciphertext 8 10 17 17 15 CD 829 = 154742504910672534362390528 100000000000000000000000000000 481968572106750915091411825223071697 481968572106750915091411825223071697 12783403948858939111232757568359375 B = CD % n 829 % 35 = 8 5 12 12 15 Plaintext letter h e l l o

We can see that even this toy example produces some extremely large numbers.

The point is that while the adversary knows n and E, he or she does not know p and q, so they cannot work out (p 1)(q 1) and thereby find D. The designer of the code, on the other hand, knows p and q because those are what he started from. So does any legitimate receiver: the designer will have told them. The security of this system depends on exactly one thing: the notoriously difficulty of factorizing a given number n into primes. For example, given n = 267 1 it took three years working on Sundays for F. N. Cole to find by hand in 1903 p and q for n = pq = 193707721 761838257287. It would be waste of time (and often combinatorially selfdefeating) for the program to grind through all possible options. Encryption strength is measured by the length of its key, which is expressed in bits. The larger the key, the greater the strength of the encryption. Using 112 computers, a graduate student decrypted one 40-bit encrypted message in a little over 7 days. In contrast, data encrypted with a 128-bit key is 309,485,009,821,345,068,724,781,056 times stronger than data encrypted with a 40-bit key. RSA Laboratories recommends that the product of p and q be on the order of 1024 bits long for corporate use and 768 bits for use with less valuable information.

5.5.3

Authentication

http://www.netip.com/articles/keith/diffie-helman.htm http://www.rsasecurity.com/rsalabs/node.asp?id=2248 http://www.scramdisk.clara.net/pgpfaq.html http://postdiluvian.org/~seven/diffie.html http://www.sans.org/rr/whitepapers/vpns/751.php http://www.fors.com/eoug97/papers/0356.htm

Chapter 5

Design with Patterns

231

Class iaik.security.dh.DHKeyAgreement http://www.cs.utexas.edu/users/chris/cs378/f98/resources/iaikdocs/iaik.security.dh.DHKeyAgree ment.html

Microsoft's 'PassPort' Out, Federation Services In It's been two years since Microsoft issued any official pronouncements on "TrustBridge," its collection of federated identity-management technologies slated to go head-to-head with competing technologies backed by the Liberty Alliance. http://www.eweek.com/article2/0,1759,1601681,00.asp?kc=ewnws052704dtx1k0200599

However, we should not forget that security comes at a cost. In theory, application programs are supposed to access hardware of the computer only through the interfaces provided by the operating system. But many application programmers who dealt with small computer operating systems of the 1970s and early 1980s often bypassed the OS, particularly in dealing with the video display. Programs that directly wrote bytes into video display memory run faster than programs that didn't. Indeed, for some applicationssuch as those that needed to display graphics on the video displaythe operating system was totally inadequate. What many programmers liked most about MS-DOS was that it stayed out of the way and let programmers write programs as fast as the hardware allowed. For this reason, popular software that ran on the IBM PC often relied upon idiosyncrasies of the IBM PC hardware.

5.6 Summary and Bibliographical Notes

Design patterns are heuristics for structuring the software modules and their interactions that are proven in practice. They yield in design for change, so the change of the computing environment has as minimal and as local effect on the code as possible. Key Points: Using the Broker pattern, a client object invokes methods of a remote server object, passing arguments and receiving a return value with each call, using syntax similar to local method calls. Each side requires a proxy that interacts with the systems runtime.

Ivan Marsic

Rutgers University

232

There are many known design patterns and I have reviewed above only few of the major ones. Many books are available, perhaps the best known are [Gamma et al., 1995] and [Buschmann et al., 1996]. The reader can also find a great amount of useful information on the web. In particular, a great deal of information is available in Hillside.nets Patterns Library: http://hillside.net/patterns/ . R. J. Wirfs-Brock, Refreshing patterns, IEEE Software, vol. 23, no. 3, pp. 45-47, May/June 2006.

Concurrent systems are a large research and practice filed and here I provide only the introductory basics. Concurrency methods are usually not covered under design patterns and it is only for the convenience sake that here they appear in the section on software design patterns. I avoided delving into the intricacies of Java threadsby no means is this a reference manual for Java threads. Concurrent programming in Java is extensively covered in [Lea, 2000] and a short review is available in [Sandn, 2004]. [Whiddett, 1987] Pthreads tutorial: http://www.cs.nmsu.edu/~jcook/Tools/pthreads/pthreads.html Pthreads tutorial from CS6210 (by Phillip Hutto): http://www.cc.gatech.edu/classes/AY2000/cs6210_spring/pthreads_tutorial.htm The Broker design pattern is described in [Buschmann et al., 1996; Vlter et al., 2005]. ICS 54: History of Public-Key Cryptography: http://www.ics.uci.edu/~ics54/doc/security/pkhistory.html Java RMI: Sun Developer Network (SDN) jGuru: Remote Method Invocation (RMI), Sun Microsystems, Inc., Online at: http://java.sun.com/developer/onlineTraining/rmi/RMI.html http://www.javaworld.com/javaworld/jw-04-2005/jw-0404-rmi.html http://www.developer.com/java/ent/article.php/10933_3455311_1 Although Java RMI works only if both client and server processes are coded in the Java programming language, there are other systems, such as CORBA (Common Object Request Broker Architecture), which work with arbitrary programming languages, including Java. A readable appraisal of the state of affairs with CORBA is available in [Henning, 2006]. Cryptography [Menezes et al., 1997], which is available for download, entirely, online at http://www.cacr.math.uwaterloo.ca/hac/.

P. Dourish, R. E. Grinter, J. Delgado de la Flor, and M. Joseph, Security in the wild: user strategies for managing security as an everyday, practical problem, Personal and Ubiquitous Computing (ACM/Springer), vol. 8, no. 6, pp. 391-401, November 2004. M. J. Ranum, Security: The root of the problem, ACM Queue (Special Issue: Surviving Network Attacks), vol. 2, no. 4, pp. 44-49, June 2004.

Chapter 5

Design with Patterns

233

H. H. Thompson and R. Ford, Perfect storm: The insider, naivety, and hostility, ACM Queue (Special Issue: Surviving Network Attacks), vol. 2, no. 4, pp. 58-65, June 2004. introducing trust and its pervasiveness in information technology

Problems
Problem 5.1

Problem 5.2
Suppose you want to employ the Publish-Subscribe (also known as Observer) design pattern in your design for Problem 2.14 (Chapter 2). Which classes should implement the Publisher interface? Which classes should implement the Subscriber interface? Explain your answer. (Note: You can introduce new classes or additional methods on the existing classes if you feel it necessary for solution.)

Problem 5.3
In the patient-monitoring scenario of Problem 2.8 (Chapter 2), assume that multiple recipients must be notified about the patient condition. Suppose that your software is to use the PublishSubscribe design pattern. Identify the key software objects and draw a UML interaction diagram to represent how software objects in the system could accomplish the notification problem.

Problem 5.4

Problem 5.5
L 2

Problem 5.6: Elevator Control

Consider the elevator control problem defined in Problem 3.7 (Chapter 3). Your task is to determine whether the Publisher-Subscriber design pattern can be applied in this design. Explain clearly your answer. If the answer is yes, identify which classes are suitable for the publisher role and which ones are suitable for the subscriber role. Explain your choices, list the events generated by the Publishers, and state explicitly for each Subscriber to which events it is subscribed to.

6 7
Up

Down

Ivan Marsic

Rutgers University

234

FULL

Figure 5-27: Parking lot occupancy monitoring, Problem 5.9.

Problem 5.7

Problem 5.8
In Section 5.3, it was stated that the standard Java idiom for condition synchronization is the statement:
while (condition) sharedObject.wait();

(a) Is it correct to substitute the yield() method call for wait()? Explain your answer and discuss any issues arising from the substitution. (b) Suppose that if substitutes for while, so we have: if (condition) sharedObject.wait() Is this correct? Explain your answer.

Problem 5.9
Parking lot occupancy monitoring, see Figure 5-27. Consider a parking lot with the total number of spaces equal to capacity. There is a single barrier gate with two poles, one for the entrance and the other for the exit. A computer in the barrier gate runs a single program which controls both poles. The program counts the current number of free spaces, denoted by occupancy, such that 0 occupancy capacity When a new car enters, the occupancy is incremented by one; conversely, when a car exits, the occupancy is decremented by one. If occupancy equals capacity, the red light should turn on to indicate that the parking is full. In order to be able to serve an entering and an exiting patron in parallel, you should design a system which runs in two threads. EnterThread controls the entrance gate and ExitThread

Chapter 5

Design with Patterns

235

: EnterThread Car requestEntry()

: SharedState

: ExitThread Car requestExit()

Figure 5-28: UML diagram template for parking lot occupancy monitoring, Problem 5.9.

Cook 2 Supplier Egg tray Cook 1 Pickup counter Waiter

Figure 5-29: Concurrency problem in a restaurant scenario, Problem 5.10.

controls the exit gate. The threads share the occupancy counter so to correctly indicate the parking-full state. Complete the UML sequence diagram in Figure 5-28 that shows how the two threads update the shared variable, i.e., occupancy.
Hint: Your key concern is to maintain the consistent shared state (occupancy) and indicate when the parking-full sign should be posted. Extraneous actions, such as issuing the ticket for an entering patron and processing the payment for an exiting patron, should not be paid attention only make a high-level remark where appropriate.

Problem 5.10
Consider a restaurant scenario shown in Figure 5-29. You are to write a simulation in Java such that each person runs in a different thread. Assume that each person takes different amount of time to complete their task. The egg tray and the pickup counter have limited capacities, Neggs and Nplates, respectively. The supplier stocks the egg tray but must wait if there are no free slots. Likewise, the cooks must hold the prepared meal if the pickup counter is full.

Problem 5.11
A priority inversion occurs when a higher-priority thread is waiting for a lower-priority thread to finish processing of a critical region that is shared by both. Although higher-priority threads normally preempt lower-priority threads, this is not possible when both share the same critical

Ivan Marsic

Rutgers University

236

region. While the higher-priority thread is waiting, a third thread, whose priority is between the first two, but it does not share the critical region, preempts the low-priority thread. Now the higher-priority thread is waiting for more than one lower-priority thread. Search the literature and describe precisely a possible mechanism to avoid priority inversion.

Problem 5.12

Problem 5.13
Use Java RMI to implement a distributed Publisher-Subscriber design pattern. Requirements: The publisher and subscribers are to be run on different machines. The naming server should be used for rendezvous only; after the first query to the naming server, the publisher should cache the contact information locally. Handle sudden (unannounced) departures of subscribers by implementing a heartbeat protocol.

Problem 5.14
Suppose that you are designing an online grocery store. The only supported payment method will be using credit cards. The information exchanges between the parties are shown in Figure 5-30. After making the selection of items for purchase, the customer will be prompted to enter information about his/her credit card account. The grocery store (merchant) should obtain this information and relay it to the bank for the transaction authorization. In order to provide secure communication, you should design a public-key cryptosystem as follows. All messages between the involved parties must be encrypted for confidentiality, so that only the appropriate parties can read the messages. Even the information about the purchased items, payment amount, and the outcome of credit-card authorization request should be kept confidential. Only the initial catalog information is not confidential. The credit card information must be encrypted by the customer so that only the bank can read it the merchant should relay it without being able to view the credit card information. For the sake of simplicity, assume that all credit cards are issued by a single bank. The message from the bank containing binary decision (approved or rejected) will be sent to the merchant, who will forward it securely to the customer. Both the merchant and customer should be able to read it. Answer the following questions about the cryptosystem that is to be developed: (a) What is the (minimum) total number of public-private key pairs ( K i+ , K i ) that must be issued? In other words, which actors need to possess a key pair, or perhaps some actors need more than one pair? (b) For each key pair i, specify which actor should issue this pair, to whom the public key K i+ should be distributed, and at what time (prior to each shopping session or once for multiple sessions). Provide an explanation for your answer!

Chapter 5

Design with Patterns

237

Customer
enter selection (items catalog) place order (selected items")

Merchant

Bank

enter credit card info (payment amount) process payment (card info")

approve transaction (card info, payment amount") notify outcome (result value) notify outcome (result value)

Figure 5-30: Information exchanges between the relevant parties. The quoted variables in the parentheses represent the parameters that are passed on when the operation is invoked.

(c) For each key pair i, show which actor holds the public key K i+ and which actor holds the private key K i . (d) For every message in Figure 5-30, show exactly which key K i+ / K i should be used in the encryption of the message and which key should be used in its decryption.

Problem 5.15
In the Model-View-Controller design pattern, discuss the merits of having Model subscribe to the Controller using the Publish-Subscribe design pattern? Argue whether Controller should subscribe to the View?

XML and Data Representation

Chapter 6

Contents
Description is always a bore, both to the describer and the describee. Disraeli

6.1 Structure of XML Documents

6.1.1 6.1.2 6.1.3 6.1.4 Syntax Document Type Definition (DTD) Namespaces XML Parsers

XML defines a standard way to add markup to documents, which facilitates representation, storage, and exchange of information. A markup language is a mechanism to identify parts of a document and to describe their logical relationships. XML stands for eXtensible Markup Language (extensible because it is not a fixed set of markup tags like HTML HyperText Markup Language). The language is standardized by the World Wide Web Consortium (W3C), and all relevant information is available at: http://www.w3.org/XML/. Structured information contains both content (words, pictures, etc.) and metadata describing what role that content plays (for example, content in a section heading has a different meaning from content in a footnote, which means something different than content in a figure caption or content in a database table, etc.). XML is not a single, predefined markup language: it is a metalanguagelanguage for defining other languageswhich lets you design your own markup language. A predefined markup language like HTML defines a specific vocabulary and grammar to describe information, and the user is unable to modify or extend either of these. Conversely, XML, being a meta-language for markup, lets you design a new markup language, with tags and the rules of their nesting that best suite your problem domain.

6.2 XML Schemas

6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 XML Schema Basics Models for Structured Content Datatypes Reuse RELAX NG Schema Language

6.3 Indexing and Linking

6.3.1 XPointer and Xpath 6.3.2 XLink 6.3.3 6.2.4

6.4 Document Transformation and XSL

6.4.1 6.4.2 6.4.3 6.4.4

6.5
6.5.1 6.5.2 6.5.3 6.5.4

6.6
6.6.1 6.6.2 6.6.3

6.7 Summary and Bibliographical Notes Problems

Why cover XML in a basic software engineering text? Because so far we dealt only with program development, but neglected data. [Brookss comment about code vs. data.] If you are writing software, you are inevitably representing structured information, whether it is a configuration file, documentation, or programs input/output data. You need to specify how data is represented and exchanged, i.e., the data format. But there is more to it.

238

Chapter 6

XML and Data Representation

239

The perception and nature of the term document has changed over the time. In the past, a document was a container of static information and it was often an end result of an application. Recently, the nature of documents changed from passive to active. The documents themselves became live applications. Witness the client-side event-handling scripting languages in Web browsers, such as JavaScript. Moreover, great deal of a programs business logic can be encoded separately, as data, rather than hard-coded as instructions. Cf. data-driven design and reflection, Chapter 7 below.

Structured Documents and Markup

The word document refers not only to traditional documents, like a book or an article, but also to the numerous of other data collections. These include vector graphics, e-commerce transactions, mathematical equations, object meta-data, server APIs, and great many other kinds of structured information. Generally, structured document is a document in which individual parts are identified and they are arranged in a certain pattern. Documents having structured information include both the content as well as what the content stands for. Consider these two documents: Unstructured Document Structured Document <letter> <sender> Mr. Charles Morse <name>Mr. Charles Morse</name> 13 Takeoff Lane <address> Talkeetna, AK 99676 <street>13 Takeoff Lane</street> <city>Talkeetna</city> <state>AK</state> 29 February, 1997 date <postal-code>99676</postal-code> </address> Mrs. Robinson </sender> 1 Entertainment Way <date>29 February, 1997</date> Los Angeles, CA 91011 <recipient> <name>Mrs. Robinson</name> Dear Mrs. Robinson, salutation <address> <street>1 Entertainment Way</street> Heres part of an update on my first day at <city>Los Angeles</city> <state>CA</state> the edge. I hope to relax and sow my wild <postal-code>91011</postal-code> oats. </address> </recipient> <salutation>Dear Mrs. Robinson,</ salutation> <body> Heres part of an update </body> closing <closing>Sincerely,</closing> <signature>Charlie</signature> signature </letter>
recipients address senders address

You probably guessed that the document on the left is a correspondence letter, because you are familiar with human conventions about composing letters. (I highlighted the prominent parts of the letter by gray boxes.) Also, postal addresses adhere to certain templates as well. Even if you never heard of a city called Talkeetna, you can quickly recognize what part of the document appears to represent a valid postal address. But, if you are a computer, not accustomed to human conventions, you would not know what the text contains. On the other hand, the document on the

letters body

Ivan Marsic

Rutgers University

240

right has clearly identified (marked) parts and their sub-parts. Parts are marked up with tags that indicate the nature of the part they surround. In other words, tags assign meaning/semantics to document parts. Markup is a form of metadata, that is, documents dictionary capturing definitions of document parts and the relationships among them. Having documents marked up enables automatic data processing and analysis. Computer can be applied to extract relevant and novel information and present to the user, check official forms whether or not they are properly filled out by users, etc. XML provides a standardized platform to create and exchange structured documents. Moreover, XML provides a platform for specifying new tags and their arrangements, that is, new markup languages. XML is different from HTML, although there is a superficial similarity. HTML is a concrete and unique markup language, while XML is a meta-languagea system for creating new markup languages. In a markup language, such as HTML, both the tag set and the tag semantics are fixed and only those will be recognized by a Web browser. An <h1> is always a first level heading and the tag <letter> is meaningless. The W3C, in conjunction with browser vendors and the WWW community, is constantly working to extend the definition of HTML to allow new tags to keep pace with changing technology and to bring variations in presentation (stylesheets) to the Web. However, these changes are always rigidly confined by what the browser vendors have implemented and by the fact that backward compatibility is vital. And for people who want to disseminate information widely, features supported only by the latest release of a particular browser are not useful. XML specifies neither semantics nor a tag set. The tags and grammar used in the above example are completely made up. This is the power of XMLit allows you to define the content of your data in a variety of ways as long as you conform to the general structure that XML requires. XML is a meta-language for describing markup languages. In other words, XML provides a facility to define tags and the structural relationships between them. Since there is no predefined tag set, there cannot be any preconceived semantics. All of the semantics of XML documents will be defined by the applications that process them.

A document has both a logical and a physical structure. The logical structure allows a document to be divided into named parts and sub-parts, called elements. The physical structure allows components of the document, called entities, to be named and stored separately, sometimes in other data files so that information can be reused and non-textual data (such as images) can be included by reference. For example, each chapter in a book may be represented by an element, containing further elements that describe each paragraph, table and image, but image data and paragraphs that are reused (perhaps from other documents) are entities, stored in separate files.

XML Standard
XML is defined by the W3C in a number of related specifications available here: http://www.w3.org/TR/. Some of these include: Extensible Markup Language (XML), current version 1.1 (http://www.w3.org/XML/Core/) Defines the syntax of XML, i.e., the base XML specification.

Chapter 6

XML and Data Representation

241

Namespaces (http://www.w3.org/TR/xml-names11) XML namespaces provide a simple method for qualifying element and attribute names used in Extensible Markup Language documents by associating them with namespaces identified by URI references. Schema (http://www.w3.org/XML/Schema) The schema language, which is itself represented in XML, provides a superset of the capabilities found in XML document type definitions (DTDs). DTDs are explained below. XML Pointer Language (XPointer) (http://www.w3.org/TR/xptr/) and XML Linking Language (XLink) (http://www.w3.org/TR/xlink/) Define a standard way to represent links between resources. In addition to simple links, like HTMLs <A> tag, XML has mechanisms for links between multiple resources and links between read-only resources. XPointer describes how to address a resource, XLink describes how to associate two or more resources. XML Path Language (XPath) (http://www.w3.org/TR/xpath20/) Xpath is a language for addressing parts of an XML document, designed to be used by both XSLT and XPointer. Extensible Stylesheet Language (XSL) (http://www.w3.org/TR/xsl/) and XSL Transformations (XSLT) (http://www.w3.org/TR/xslt/) Define the standard stylesheet language for XML.

Unlike programming languages, of which there are many, XML is universally accepted by all vendors. The rest of the chapter gives a brief overview and relevant examples.

6.1 Structure of XML Documents

6.1.1 Syntax

Syntax defines how the words of a language are arranged into phrases and sentences and how components (like prefixes and suffixes) are combined to make words. XML documents are composed of markup and contentcontent (text) is hierarchically structured by markup tags. There are six kinds of markup that can occur in an XML document: elements, entity references, comments, processing instructions, marked sections, and document type declarations. The following subsections introduce each of these markup concepts.

Elements
Elements indicate logical parts of a document and they are the most common form of markup. An element is delimited by tags which are surrounded by angle brackets (<, > and </, />). The tags give a name to the document part they surroundthe element name should be given to convey the nature or meaning of the content. A non-empty element begins with a start-tag, <tag>, and ends with an end-tag, </tag>. The text between the start-tag and end-tag is called the elements content. In the above example of a letter document, the element

Ivan Marsic

Rutgers University

242

<salutation>Dear Mrs. Robinson,</salutation> indicates the salutation part of the letter. Rules for forming an element name are: Must start with a letter character Can include all standard programming language identifier [0-9A-Za-z] as well as underscore _, hyphen -, and colon : Is case sensitive, so <name> and <Name> are different element names characters, i.e.,

Some elements may be empty, in which case they have no content. An empty element can begin and end at the same place in which case it is denoted as <tag/>. Elements can contain subelements. The start tag of an element can have, in addition to the element name, related (attribute, value) pairs. Elements can also have mixed content where character data can appear alongside subelements, and character data is not confined to the deepest subelements. Here is an example:
<salutation>Dear <name>Mrs. Robinson</name>, </salutation>

Notice the text appearing between the element <salutation> and its child element <name>.

Attributes
Attributes are name-value pairs that occur inside start-tags after the element name. A start tag can have zero or more attributes. For example,
<date format="English_US">

is an element named date with the attribute format having the value English_US, meaning that month is shown first and named in English. Attribute names are formed using the same rules as element names (see above). In XML, all attribute values must be quoted. Both single and double quotes can be used, provided they are correctly matched.

Entities and Entity References

XML reserves some characters to distinguish markup from plain text (content). The left angle bracket, <, for instance, identifies the beginning of an elements start- or end-tag. To support the reserved characters as part of content and avoid confusion with markup, there must be an alternative way to represent them. In XML, entities are used to represent these reserved characters. Entities are also used to refer to often repeated or varying text and to include the content of external files. In this sense, entities are similar to macros. Every entity must have a unique name. Defining your own entity names is discussed in the section on entity declarations (Section 6.1.2 below). In order to use an entity, you simply reference it by name. Entity references begin with the ampersand and end with a semicolon, like this &entityname;. For example, the lt entity inserts a literal < into a document. So to include the string <non-element> as plain text, not markup, inside an XML document all reserved characters should be escaped, like so &lt;non-element&gt;. A special form of entity reference, called a character reference, can be used to insert arbitrary Unicode characters into your document. This is a mechanism for inserting characters that cannot be typed directly on your keyboard.

Chapter 6

XML and Data Representation

243

Character references take one of two forms: decimal references, &#8478;, and hexadecimal references, &#x211E;. Both of these refer to character number U+211E from Unicode (which is the standard Rx prescription symbol).

Comments
A comment begins with the characters <!-- and ends with -->. A comment can span multiple lines in the document and contain any data except the literal string --. You can place comments anywhere in your document outside other markup. Here is an example:
<!-- ******************** My comment is imminent. -->

Comments are not part of the textual content of an XML document and the parser will ignore them. The parser is not required to pass them along to the application, although it may do so.

Processing Instructions
Processing instructions (PIs) allow documents to contain instructions for applications that will import the document. Like comments, they are not textually part of the XML document, but this time around the XML processor is required to pass them to an application. Processing instructions have the form: <?name pidata?>. The name, called the PI target, identifies the PI to the application. For example, you might have <?font start italic?> and <?font end italic?>, which indicate the XML processor to start italicizing the text and to end, respectively. Applications should process only the targets they recognize and ignore all other PIs. Any data that follows the PI target is optional; it is for the application that recognizes the target. The names used in PIs may be declared as notations in order to formally identify them. Processing instruction names beginning with xml are reserved for XML standardization.

CDATA Sections
In a document, a CDATA section instructs the parser to ignore the reserved markup characters. So, instead of using entities to include reserved characters in the content as in the above example of &lt;non-element&gt;, we can write:
<![CDATA[ <non-element> ]]>

Between the start of the section, <![CDATA[ and the end of the section, ]]>, all character data are passed verbatim to the application, without interpretation. Elements, entity references, comments, and processing instructions are all unrecognized and the characters that comprise them are passed literally to the application. The only string that cannot occur in a CDATA section is ]]>.

Ivan Marsic

Rutgers University

244

Document Type Declarations (DTDs)

Document type declarations (DTDs) are reviewed in Section 6.1.2 below. DTD is used mainly to define constraints on the logical structure of documents, that is, the valid tags and their arrangement/ordering.

This is about as much as an average user needs to know about XML. Obviously, it is simple and concise. XML is designed to handle almost any kind of structured datait constrains neither the vocabulary (set of tags) nor the grammar (rules of how the tags combine) of the markup language that the user intends to create. XML allows you to create your own tag names. Another way to think of it is that XML only defines punctuation symbols and rules for forming sentences and paragraphs, but it does not prescribe any vocabulary of words to be used. Inventing the vocabulary is left to the language designer. But for any given application, it is probably not meaningful for tags to occur in a completely arbitrary order. From a strictly syntactic point of view, there is nothing wrong with such an XML document. So, if the document is to have meaning, and certainly if you are writing a stylesheet or application to process it, there must be some constraint on the sequence and nesting of tags, stating for example, that a <chapter> that is a sub-element of a <book> tag, and not the other way around. These constraints can be expressed using an XML schema (Section 6.2 below).

XML Document Example

The letter document shown initially in this chapter can be represented in XML as follows: Listing 6-1: Example XML document of a correspondence letter.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 <?xml version="1.0" encoding="UTF-8"?> <!-- Comment: A personal letter marked up in XML. --> <letter language="en-US" template="personal"> <sender> <name>Mr. Charles Morse</name> <address kind="return"> <street>13 Takeoff Lane</street> <city>Talkeetna</city><state>AK</state> <postal-code>99676</postal-code> </address> </sender> <date format="English_US">February 29, 1997</date> <recipient> <name>Mrs. Robinson</name> <address kind="delivery"> <street>1 Entertainment Way</street> <city>Los Angeles</city><state>CA</state> <postal-code>91011</postal-code> </address> </recipient> <salutation style="formal">Dear Mrs. Robinson,</ salutation> <body> Here's part of an update ... </body> <closing>Sincerely,</closing>

Chapter 6

XML and Data Representation

245

XML language for letters, variant 1

XML language for letters, variant 2

<address kind="return"> <street>13 Takeoff Lane</street> <city>Talkeetna</city> <state>AK</state> <postal-code>99676</postal-code> </address>

<address kind="return street="13 Takeoff Lane city="Talkeetna" state="AK zip="99676" />

Translator

Figure 6-1: Different XML languages can be defined for the same domain and/or concepts. In such cases, we need a translator to translate between those languages.
26 27 <signature>Charlie</signature> </letter>

Line 1 begins the document with a processing instruction <?xml ... ?>. This is the XML declaration, which, although not required, explicitly identifies the document as an XML document and indicates the version of XML to which it was authored. A variation on the above example is to define the components of a postal address (lines 69 and 1417) as element attributes:
<address kind="return" street="13 Takeoff Lane" city="Talkeetna" state="AK" postal-code="99676" />

Notice that this element has no content, i.e., it is an empty element. This produces a more concise markup, particularly suitable for elements with well-defined, simple, and short content. One quickly notices that XML encourages naming the elements so that the names describe the nature of the named object, as opposed to describing how it should be displayed or printed. In this way, the information is self-describing, so it can be located, extracted, and manipulated as desired. This kind of power has previously been reserved for organized scalar information managed by database systems. You may have also noticed a potential hazard that comes with this freedomsince people may define new XML languages as they please, how can we resolve ambiguities and achieve common understanding? This is why, although the core XML is very simple, there are many XML-related standards to handle translation and specification of data. The simplest way is to explicitly state the vocabulary and composition rules of an XML language and enforce those across all the involved parties. Another option, as with natural languages, is to have a translator in between, as illustrated in Figure 6-1. The former solution employs XML Schemas (introduced in Section 6.2 below), and the latter employs transformation languages (introduced in Section 6.4 below).

Well-Formedness
A text document is an XML document if it has a proper syntax as per the XML specification. Such document is called a well-formed document. An XML document is well-formed if it conforms to the XML syntax rules: Begins with the XML declaration <?xml ... ?> Has exactly one root element, called the root or document, and no part of it can appear in the content of any other element

Ivan Marsic

Rutgers University

246

Contains one or more elements delimited by start-tags and end-tags (also remember that XML tags are case sensitive) All elements are closed, that is all start-tags must match end-tags All elements must be properly nested within each <outer><inner>inner content</inner></outer> All attribute values must be within quotations XML entities must be used for special characters. Each of the parsed entities that are referenced directly or indirectly within the document is well-formed. other, such as

Even if documents are well-formed they can still contain errors, and those errors can have serious consequences. XML Schemas (introduced in Section 6.2 below) provide further level of error checking. A well-formed XML document may in addition be valid if it meets constraints specified by an associated XML Schema.

Document- vs. Data-Centric XML

Generally speaking, there are two broad application areas of XML technologies. The first relates to document-centric applications, and the second to data-centric applications. Because XML can be used in so many different ways, it is important to understand the difference between these two categories. (See more at http://www.xmleverywhere.com/newsletters/20000525.htm) Initially, XMLs main application was in semi-structured document representation, such as technical manuals, legal documents, and product catalogs. The content of these documents is typically meant for human consumption, although it could be processed by any number of applications before it is presented to humans. The key element of these documents is semistructured marked-up text. A good example is the correspondence letter in Listing 6-1 above. By contrast, data-centric XML is used to mark up highly structured information such as the textual representation of relational data from databases, financial transaction information, and programming language data structures. Data-centric XML is typically generated by machines and is meant for machine consumption. It is XMLs natural ability to nest and repeat markup that makes it the perfect choice for representing these types of data. Key characteristics of data-centric XML: The ratio of markup to content is high. The XML includes many different types of tags. There is no long-running text. The XML includes machine-generated information, such as the submission date of a purchase order using a date-time format of year-month-day. A human authoring an XML document is unlikely to enter a date-time value in this format. The tags are organized in a highly structured manner. Order and positioning matter, relative to other tags. For example, TBD Markup is used to describe what a piece of information means rather than how it should be presented to a human.

Chapter 6

XML and Data Representation

247

An interesting example of data-centric XML is the XML Metadata Interchange (XMI), which is an OMG standard for exchanging metadata information via XML. The most common use of XMI is as an interchange format for UML models, although it can also be used for serialization of models of other languages (metamodels). XMI enables easy interchange of metadata between UML-based modeling tools and MOF (Meta-Object Facility)-based metadata repositories in distributed heterogeneous environments. For more information see here: http://www.omg.org/technology/documents/formal/xmi.htm.

6.1.2

Document Type Definition (DTD)

Document Type Definition (DTD) is a schema language for XML inherited from SGML, used initially, before XML Schema was developed. DTD is one of ways to define the structure of XML documents, i.e., the documents metadata. Syntactically, a DTD is a sequence of declarations. There are four kinds of declarations in XML: (1) element type declarations, used to define tags; (2) attribute list declarations, used to define tag attributes; (3) entity declarations, used to define entities; and, (4) notation declarations, used to define data type notations. Each declaration has the form of a markup representation, starting with a keyword followed by the production rule that specifies how the content is created: <!keyword production-rule> where the possible keywords are: ELEMENT, ATTLIST (for attribute list), ENTITY, and NOTATION. Next, I describe these declarations.

Element Type Declarations

Element type declarations identify the names of elements and the nature of their content, thus putting a type constraint on the element. A typical element type declaration looks like this:
<!ELEMENT <!ELEMENT
Declaration type

chapter title
Element name

(title, paragraph+, figure?)> (#PCDATA)>

Elements content model (definition of allowed content: list of names of child elements)

The first declaration identifies the element named chapter. Its content model follows the element name. The content model defines what an element may contain. In this case, a chapter must contain paragraphs and title and may contain figures. The commas between element names indicate that they must occur in succession. The plus after paragraph indicates that it may be repeated more than once but must occur at least once. The question mark after figure indicates that it is optional (it may be absent). A name with no punctuation, such as title, must occur exactly once. The following table summarizes the meaning of the symbol after an element: Kleene symbol Meaning none The element must occur exactly once ? The element is optional (zero or one occurrence allowed) * The element can be skipped or included one or more times + The element must be included one or more times Declarations for paragraphs, title, figures and all other elements used in any content model must also be present for an XML processor to check the validity of a document. In addition to element

Ivan Marsic

Rutgers University

248

names, the special symbol #PCDATA is reserved to indicate character data. The PCDATA stands for parseable character data. Elements that contain only other elements are said to have element content. Elements that contain both other elements and #PCDATA are said to have mixed content. For example, the definition for paragraphs might be
<!ELEMENT paragraph (#PCDATA | quote)*>

The vertical bar indicates an or relationship, the asterisk indicates that the content is optional (may occur zero or more times); therefore, by this definition, paragraphs may contain zero or more characters and quote tags, mixed in any order. All mixed content models must have this form: #PCDATA must come first, all of the elements must be separated by vertical bars, and the entire group must be optional. Two other content models are possible: EMPTY indicates that the element has no content (and consequently no end-tag), and ANY indicates that any content is allowed. The ANY content model is sometimes useful during document conversion, but should be avoided at almost any cost in a production environment because it disables all content checking in that element.

Attribute List Declarations

Elements which have one or more attributes are to be specified in the DTD using attribute list type declarations. An example for a figure element could be like so
<!ATTLIST
Declaration type

figure
Name of the associated element

caption scaling
Names of attributes

CDATA CDATA
Data type

#REQUIRED #FIXED "100%">

Keyword or default value

Repeat for each attribute of the element

The CDATA as before stands for character data and #REQUIRED means that the caption attribute of figure has to be present. Other marker could be #FIXED with a value, which means this attribute acts like a constant. Yet another marker is #IMPLIED, which indicates an optional attribute. Some more markers are ID and enumerated data type like so
<!ATTLIST person sibling (brother | sister) #REQUIRED>

Enumerated attributes can take one of a list of values provided in the declaration.

Entity Declarations
As stated above, entities are used as substitutes for reserved characters, but also to refer to often repeated or varying text and to include the content of external files. An entity is defined by its name and an associated value. An internal entity is the one for which the parsed content (replacement text) lies inside the document, like so:
<!ENTITY
Declaration type

substitute
Entity name

"This text is often repeated.">

Entity value (any literal) single or double quotes can be used, but must be properly matched

Once the above example entity is defined, it can be used in the XML document as &substitute; anywhere where the full text should appear. Entities can contain markup as

Chapter 6

XML and Data Representation

249

well as plain text. For example, this declaration defines &contact; as an abbreviation for persons contact information that may be repeated multiple times in one or more documents:
<!ENTITY contact '<a href="mailto:[email protected]"> e-mail</a><br> <a href="732-932-4636.tel">telephone</a> <address>13 Takeoff Lane<br> Talkeetna, AK 99676</address> '>

Conversely, the content of the replacement text of an external entity resides in a file separate from the XML document. The content can be accessed using either system identifier, which is a URI (Uniform Resource Identifier, see Appendix C) address, or a public identifier, which serves as a basis for generating a URI address. Examples are:
<!ENTITY <!ENTITY
Declaration type

contact surrogate
Entity name

SYSTEM "http://any.company.com/contact.xml"> PUBLIC "-//home/mrsmith/text"

SYSTEM or PUBLIC identifier, followed by the external ID (URI or other)

Notation Declarations
Notations are used to associate actions with entities. For example, a PDF file format can be associated with the Acrobat application program. Notations identify, by name, the format of these actions. Notation declarations are used to provide an identifying name for the notation. They are used in entity or attribute list declarations and in attribute specifications. This is a complex and controversial feature of DTD and the interested reader should seek details elsewhere.

DTD in Use
A DTD can be embedded in the XML document for which it describes the syntax rules and this is called an internal DTD. The alternative is to have the DTD stored in one or more separate files, called external DTD. External DTDs are preferable since they can be reused in different XML documents by different users. The reader should be by now aware of the benefits of modular design, a key one being able to (re-)use modules that are tested and fixed by previous users. However, this also means that if the reused DTD module is changed, all documents that use the DTD must be tested against the new DTD and possibly modified to conform to the changed DTD. In an XML document, external DTDs are referred to with a DOCTYPE declaration in the second line of the XML document (after the first line: <?xml ... ?>) as seen in Listing 6-3 below. The following fragment of DTD code defines the production rules for constructing book documents.

Listing 6-2: Example DTD for a postal address element. File name: address.dtd
1 2 3 4 5 6 <!ELEMENT <!ATTLIST <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT address (street+, city, state, postal-code)> address kind (return | delivery) #IMPLIED> street (#PCDATA)> city (#PCDATA)> state (#PCDATA)> postal-code (#PCDATA)>

Ivan Marsic

Rutgers University

250

Line 1 shows the element address definition, where all four sub-elements are required, and the street sub-element can appear more than once. Line 2 says that address has an optional attribute, kind, of the enumerated type. We can (re-)use the postal address declaration as an external DTD, for example, in an XML document of a correspondence letter as shown in Listing 6-3.

Listing 6-3: Example correspondence letter that uses an external DTD.

1 2 3 4 4a 5 6 7 8 9 10 11 12 13 14 <?xml version="1.0"?> <!-- Comment: Person DTD --> <!DOCTYPE letter SYSTEM "http://any.website.net/address.dtd" [ <!ELEMENT letter (sender?, recipient+, body)> <!ATTLIST letter language (en-US | en-UK | fr) #IMPLIED template (personal | business) #IMPLIED> <!ELEMENT sender (name, address)> <!ELEMENT recipient (name, address)> <!ELEMENT name (#PCDATA)> <!ELEMENT body ANY> ]> <letter language="en-US" template="personal"> <sender> <name>Mr. Charles Morse</name> <address kind="return"> . . . <!-- continued as in Listing 6-1 above -->

In the above DTD document, Lines 2 9 define the DTD for a correspondence letter document. The complete DTD is made up of two parts: (1) the external DTD subset, which in this case imports a single external DTD named address.dtd in Line 2; and (2) the internal DTD subset contained between the brackets in Lines 3 8. The external DTD subset will be imported at the time the current document is parsed. The address element is used in Lines 5 and 6. The content of the body of letter is specified using the keyword ANY (Line 8), which means that a body element can contain any content, including mixed content, nested elements, and even other body elements. Using ANY is appropriate initially when beginning to design the DTD and document structure to get quickly to a working version. However, it is a very poor practice to use ANY in finished DTD documents.

Limitations of DTDs
DTD provided the first schema for XML documents. Their limitations include: Language inconsistency since DTD uses a non-XML syntax Failure to support namespace integration Lack of modular vocabulary design Rigid content models (cannot derive new type definitions based on the old ones) Lack of integration with data-oriented applications

Chapter 6

XML and Data Representation

251

http://any.website.net/book
title author figure chapter caption paragraph

http://any.website.net/person
title name phone address gender email

Figure 6-2: Example XML namespaces providing context to individual names. Conversely, XML Schema allows much more expressive and precise specification of the content of XML documents. This flexibility also carries the price of complexity.

W3C is making efforts to phase DTDs out. XML Schema is described in Section 6.2 below.

6.1.3

Namespaces

Inventing new languages is an arduous task, so it will be beneficial if we can reuse (parts of) an existing XML language (defined by a schema). Also, there are many occasions when an XML document needs to use markups defined in multiple schemas, which may have been developed independently. As a result, it may happen that some tag names may be non-unique. For example, the word title is used to signify the name of a book or work of art, a form of nomenclature indicating a persons status, the right to ownership of property, etc. People easily figure out context, but computers are very poor at absorbing contextual information. To simplify the computers task and give a specific meaning to what might otherwise be an ambiguous term, we qualify the term with and additional identifiera namespace identifier. An XML namespace is a collection of names, used as element names or attribute names, see examples in Figure 6-2. The C++ programming language defines namespaces and Java package names are equivalent to namespaces. Using namespaces, you can qualify your elements as members of a particular context, thus eliminating the ambiguity and enabling namespace-aware applications to process your document correctly. In other words: Qualified name (QName) = Namespace identifier + Local name A namespace is declared as an attribute of an element. The general form is as follows:
<bk:tagName xmlns
mandatory

:bk
prefix

= "http://any.website.net/book" />
namespace name

There are two forms of namespace declarations due to the fact that the prefix is optional. The first form binds a prefix to a given namespace name. The prefix can be any string starting with a letter, followed by any combination of digits, letters, and punctuation signs (except for the colon : since it is used to separate the mandatory string xmlns from the prefix, which indicates that we are referring to an XML namespace). The namespace name, which is the attribute value, must be a valid, unique URI. However, since all that is required from the name is its uniqueness, a URL

Ivan Marsic

Rutgers University

252

such as http://any.website.net/schema also serves the purpose. Note that this does not have to point to anything in particularit is merely a way to uniquely label a set of names. The namespace is in effect within the scope of the element for which it is defined as an attribute. This means that the namespace is effective for all the nested elements, as well. The scoping properties of XML namespaces are analogous to variable scoping properties in programming languages, such as C++ or Java. The prefix is used to qualify the tag names, as in the following example: Listing 6-4: Example of using namespaces in an XML document.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <book> <bk:cover xmlns:bk="http://any.website.net/book"> <bk:title>A Book About Namespaces</bk:title> <bk:author>Anonymous</bk:title> <bk:isbn number="1881378241"/> </bk:cover> <bk2:chapter xmlns:bk2="http://any.website.net/book" ch_name="Introduction"> <bk2:paragraph> In this chapter we start from the beginning. ... </bk2:paragraph> . . . </bk2:chapter> Scope of "bk" Scope of "bk2" Scope of default n.s.

As can be seen, the namespace identifier must be declared only in the outermost element. In our case, there are two top-level elements: <bk:cover> and <bk:chapter>, and their embedded elements just inherit the namespace attribute(s). All the elements of the namespace are prefixed with the appropriate prefix, in our case bk. The actual prefixs name is not important, so in the above example I define bk and bk2 as prefixes for the same namespace (in different scopes!). Notice also that an element can have an arbitrary number of namespace attributes, each defining a different prefix and referring to a different namespace. In the second form, the prefix is omitted, so the elements of this namespace are not qualified. The namespace attribute is bound to the default namespace. For the above example (Listing 6-4), the second form can be declared as: Listing 6-5: Example of using a default namespace.
1 2 3 4 5 6 7 8 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <book> <cover xmlns="http://any.website.net/book"> <title>A Book About Namespaces</title> <author>Anonymous</title> <isbn number="1881378241"/> </cover> . . .

Notice that there can be at most one default namespace declared within a given scope. In Listing 6-5, we can define another default namespace in the same document, but its scope must not overlap with that of the first one.

Chapter 6

XML and Data Representation

253

6.1.4

XML Parsers

The parsers define standard APIs to access and manipulate the parsed XML data. The two most popular parser APIs are DOM (Document Object Model) based and SAX (Simple API for XML). See Appendix E for a brief review of DOM. SAX and DOM offer complementary paradigms to access the data contained in XML documents. DOM allows random access to any part of a parsed XML document. To use DOM APIs, the parsed objects must be stored in the working memory. Conversely, SAX provides no storage and presents the data as a linear stream. With SAX, if you want to refer back to anything seen earlier you have to implement the underlying mechanism yourself. For example, with DOM an application program can import an XML document, modify it in arbitrary order, and write back any time. With SAX, you cannot perform the editing arbitrarily since there is no stored document to edit. You would have to edit it by filtering the stream, as it flows, and write back immediately.

Event-Oriented Paradigm: SAX

SAX (Simple API for XML) is a simple, event-based API for XML parsers. The benefit of an event-based API is that it does not require the creation and maintenance of an internal representation of the parsed XML document. This makes possible parsing XML documents that are much larger than the available system memory would allow, which is particularly important for small terminals, such as PDAs and mobile phones. Because it does not require storage behind its API, SAX is complementary to DOM.

Ivan Marsic

Rutgers University

254

Initiating the parser . . . Parser parser = ParserFactory.makeParser ("com.sun.xml.parser.Parser"); parser.setDocumentHandler(new DocumentHandlerImpl()); parser.parse (input); . . . DocumentHandler Interface public void startDocument()throws SAXException{} public void endDocument()throws SAXException{} public void startElement(String name, AttributeList attrs) throws SAXException{} public void endElement(String name)throws SAXException{} public void characters(char buf [], int offset, int len)throws SAXException{} <?xml ...> Event triggering in SAX parser:

startDocument

startElement <element attr1=val1> characters This is a test. endElement </element> <element attr1=val2/> endDocument end of the document

Document Handler

Figure 6-3: SAX parser Java example. SAX provides events for the following structural information for XML documents: The start and end of the document Document type declaration (DTD) The start and end of elements Attributes of each element Character data Unparsed entity declarations Notation declarations Processing instructions

Object-Model Oriented Paradigm: DOM

DOM (Document Object Model)

Practical Issues
Additional features relevant for both event-oriented and object-model oriented parsers include: Validation against a DTD

Chapter 6

XML and Data Representation

255

Validation against an XML Schema Namespace awareness, i.e., the ability to determine the namespace URI of an element or attribute

These features affect the performance and memory footprint of a parser, so some parsers do not support all the features. You should check the documentation for the particular parser as to the list of supported features.

6.2 XML Schemas

Although there is no universal definition of schema, generally scholars agree that schemas are abstractions or generalizations of our perceptions of the world around us, which is molded by our experience. Functionally, schemas are knowledge structures that serve as heuristics which help us evaluate new information. An integral part of schema is our expectations of people, place, and things. Schemas provide a mechanism for describing the logical structure of information, in the sense of what elements can or should be present and how they can be arranged. Deviant news results in violation of these expectations, resulting in schema incongruence. In XML, schemas are used to make a class of documents adhere to a particular interface and thus allow the XML documents to be created in a uniform way. Stated another way, schemas allow a document to communicate meta-information to the parser about its content, or its grammar. Metainformation includes the allowed sequence and arrangement/nesting of tags, attribute values and their types and defaults, the names of external files that may be referenced and whether or not they contain XML, the formats of some external (non-XML) data that may be referenced, and the entities that may be encountered. Therefore, schema defines the document production rules. XML documents conforming to a particular schema are said to be valid documents. Notice that having a schema associated with a given XML document is optional. If there is a schema for a given document, it must appear before the first element in the document. Here is a simple example to motivate the need for schemas. In Section 6.1.1 above I introduced an XML representation of a correspondence letter and used the tags <letter>, <sender>, <name>, <address>, <street>, <city>, etc., to mark up the elements of a letter. What if somebody used the same vocabulary in a somewhat different manner, such as the following? Listing 6-6: Variation on the XML example document from Listing 6-1.
1 2 3 4 5 6 7 8 9 10 11 12 <?xml version="1.0" encoding="UTF-8"?> <letter> <sender>Mr. Charles Morse</sender> <street>13 Takeoff Lane</street> <city>Talkeetna, AK 99676</city> <date>29.02.1997</date> <recipient>Mrs. Robinson</recipient> <street>1 Entertainment Way</street> <city>Los Angeles, CA 91011</city> <body> Dear Mrs. Robinson,

Ivan Marsic

Rutgers University

256

http://www.w3.org/2001/XMLSchema
schema string element complexType sequence boolean

http://any.website.net/letter
letter sender address recipient street city This is the vocabulary that XML Schema provides to define your new vocabulary salutation name

<?xml version="1.0" encoding="UTF-8"?> <lt:letter xmlns:lt ="http://any.website.net/letter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://any.website.net/letter http://any.website.net/letter/letter.xsd" lt:language="English_US" lt:template="personal"> <lt:sender> ... </lt:letter>

An instance document that conforms to the letter schema

Figure 6-4: Using XML Schema. Step 1: use the Schema vocabulary to define a new XML language (Listing 6-7). Step 2: use both to produce valid XML documents (Listing 6-8).
13 14 15 16 17 18 Here's part of an update ... Sincerely, </body> <signature>Charlie</signature> </letter>

We can quickly figure that this document is a letter, although it appears to follow different rules of production than the example in Listing 6-1 above. If asked whether Listing 6-6 represents a valid letter, you would likely respond: It probably does. However, to support automatic validation of a document by a machine, we must precisely specify and enforce the rules and constraints of composition. Machines are not good at handling ambiguity and this is what schemas are about. The purpose of a schema in markup languages is to: Allow machine validation of document structure Establish a contract (how an XML document will be structured) between multiple parties who are exchanging XML documents

There are many other schemas that are used regularly in our daily activities. Another example schema was encountered in Section 2.3.3the schema for representing the use cases of a system under discussion, Figure 2-6.

6.2.1

XML Schema Basics

XML Schema provides the vocabulary to state the rules of document production. It is an XML language for which the vocabulary is defined using itself. That is, the elements and datatypes that

Chapter 6

XML and Data Representation

257

are used to construct schemas, such as <schema>, <element>, <sequence>, <string>, etc., come from the http://www.w3.org/2001/XMLSchema namespace, see Figure 6-4. The XML Schema namespace is also called the schema of schemas, for it defines the elements and attributes used for defining new schemas. The first step involves defining a new language (see Figure 6-4). The following is an example schema for correspondence letters, an example of which is given in Listing 6-1 above.

Listing 6-7: XML Schema for correspondence letters (see an instance in Listing 6-1).
1 <?xml version="1.0" encoding="UTF-8"?> 2 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://any.website.net/letter" 2a xmlns="http://any.website.net/letter" 2b elementFormDefault="qualified"> 2c <xsd:element name="letter"> 3 <xsd:complexType> 4 5 <xsd:sequence> <xsd:element name="sender" type="personAddressType" 6 6a minOccurs="1" maxOccurs="1"/> <xsd:element name="date" type="xsd:date" minOccurs="0"/> 7 8 <xsd:element name="recipient" type="personAddressType"/> <xsd:element name="salutation" type="xsd:string"/> 9 10 <xsd:element name="body" type="xsd:string"/> 11 <xsd:element name="closing" type="xsd:string"/> 12 <xsd:element name="signature" type="xsd:string"/> 13 </xsd:sequence> <xsd:attribute name="language" type="xsd:language"/> 14 15 <xsd:attribute name="template" type="xsd:string"/> 16 </xsd:complexType> 17 </xsd:element> <xsd:complexType name="personAddressType"> 18 19 <xsd:sequence> 20 <xsd:element name="name" type="xsd:string"/> <xsd:element ref="address"/> 21 22 </xsd:sequence> 23 </xsd:complexType> 24 <xsd:element name="address"> 25 <xsd:complexType> 26 <xsd:sequence> 27 <xsd:element name="street" type="xsd:string" 27a minOccurs="1" maxOccurs="unbounded"/> 28 <xsd:element name="city" type="xsd:string"/> 29 <xsd:element name="state" type="xsd:string"/> 30 <xsd:element name="postal-code" type="xsd:string"/> 31 </xsd:sequence> 32 </xsd:complexType> 33 </xsd:element> 34 </xsd:schema>

The graphical representation of document structure defined by this schema is shown in Figure 6-5. The explanation of the above listing is as follows: Line 1: This indicates that XML Schemas are XML documents.

Ivan Marsic

Rutgers University

258

anonymous type

lt:sender

lt:personAddressType lt:name

lt:date lt:recipient lt:salutation

lt:sender lt:address

lt:letter

anonymous type lt:body lt:closing lt:city lt:signature lt:address lt:state lt:language lt:postal-code lt:template

lt:street

? ?

XML Schema symbols

<sequence> <element> immediately within <schema>, i.e. global <group> of elements

<choice>

<element> not immediately within <schema>, i.e. local

<element> reference

<all>

<element> has sub-elements (not shown)

<attribute> of an <element>

Kleene operators:
(no indicator) Required Optional

<element> has sub-elements (shown) One and only one None or one (minOccurs = 0, maxOccurs = 1) None, one, or more (minOccurs = 0, maxOccurs = ) One or more (minOccurs = 1, maxOccurs = ) element values must be unique

<attributeGroup>

? + !

Optional, repeatable Required, repeatable Unique

Figure 6-5: Document structure defined by correspondence letters schema (see Listing 6-7). NOTE: The symbolic notation is inspired by the one used in [McGovern et al., 2003]. Line 2: Declares the xsd: namespace. A common convention is to use the prefix xsd: for elements belonging to the schema namespace. Also notice that all XML Schemas have <schema> as the root elementthe rest of the document is embedded into this element. Line 2a: Declares the target namespace as http://any.website.net/letterthe elements defined by this schema are to go in the target namespace. Line 2b: The default namespace is set to http://any.website.net/lettersame as the target namespaceso the elements of this namespace do not need the namespace qualifier/prefix (within this schema document). Line 2c: This directive instructs the instance documents which conform to this schema that any elements used by the instance document which were declared in this schema must be namespace qualified. The default value of elementFormDefault (if not specified) is

Chapter 6

XML and Data Representation

259

"unqualified". The corresponding directive about qualifying the attributes is attributeFormDefault, which can take the same values. Lines 317: Define the root element <letter> as a compound datatype (xsd:complexType) comprising several other elements. Some of these elements, such as <salutation> and <body>, contain simple, predefined datatype xsd:string. Others, such as <sender> and <recipient>, contain compound type personAddressType which is defined below in this schema document (lines 1823). This complex type is also a sequence, which means that all the named elements must appear in the sequence listed. The letter element is defined as an anonymous type since it is defined directly within the element definition, without specifying the attribute name of the <xsd:complexType> start tag (line 4). This is called inlined element declaration. Conversely, the compound type personAddressType, defined as an independent entity in line 18 is a named type, so it can be reused by other elements (see lines 6 and 8). Line 6a: The multiplicity attributes minOccurs and maxOccurs constrain the number of occurrences of the element. The default value of these attributes equals to 1, so line 6a is redundant and it is omitted for the remaining elements (but, see lines 7 and 27a). In general, an element is required to appear in an instance document (defined below) when the value of minOccurs is 1 or more. Line 7: Element <date> is of the predefined type xsd:date. Notice that the value of minOccurs is set to 0, which indicates that this element is optional. Lines 1415: Define two attributes of the element <letter>, that is, language and template. The language attribute is of the built-in type xsd:language (Section 6.2.3 below). Lines 1823: Define our own personAddressType type as a compound type comprising persons name and postal address (as opposed to a business-address-type). Notice that the postal <address> element is referred to in line 21 (attribute ref) and it is defined elsewhere in the same document. The personAddressType type is extended as <sender> and <recipient> in lines 6 and 8, respectively. Lines 2433: Define the postal <address> element, referred to in line 21. Of course, this could have been defined directly within the personAddressType datatype, as an anonymous sub-element, in which case it would not be reusable. (Although the element is not reused in this schema, I anticipate that an external schema may wish to reuse it, see Section 6.2.4 below.) Line 27a: The multiplicity attribute maxOccurs is set to unbounded, to indicate that the street address is allowed to extend over several lines. Notice that Lines 2a and 2b above accomplish two different tasks. One is to declare the namespace URI that the letter schema will be associated with (Line 2a). The other task is to define the prefix for the target namespace that will be used in this document (Line 2b). The reader may wonder whether this could have been done in one line. But, in the spirit of the modularity principle, it is always to assign different responsibilities (tasks) to different entities (in this case different lines).

Ivan Marsic

Rutgers University

260

The second step is to use the newly defined schema for production of valid instance documents (see Figure 6-4). An instance document is an XML document that conforms to a particular schema. To reference the above schema in letter documents, we do as follows:

conforms-to

Schema document

Instance documents

Listing 6-8: Referencing a schema in an XML instance document (compare to Listing 6-1)
1 <?xml version="1.0" encoding="UTF-8"?> 2 <!-- Comment: A personal letter marked up in XML. --> 3 <lt:letter xmlns:lt ="http://any.website.net/letter" 3a xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 3b xsi:schemaLocation="http://any.website.net/letter 3c http://any.website.net/letter/letter.xsd" 3d lt:language="en-US" lt:template="personal"> 4 <lt:sender> ... <!-- similar to Listing 6-1 --> 10 </lt:sender> ... <!-- similar to Listing 6-1 --> 25 </lt:letter>

The above listing is said to be valid unlike Listing 6-1 for which we generally only know that it is well-formed. The two documents (Listings 6-1 and 6-8) are the same, except for referencing the letter schema as follows: Step 1 (line 3): Tell a schema-aware XML processor that all of the elements used in this instance document come from the http://any.website.net/letter namespace. All the element and attribute names will be prefaced with the lt: prefix. (Notice that we could also use a default namespace declaration and avoid the prefix.) Step 2 (line 3a): Declare another namespace, the XMLSchema-instance namespace, which contains a number of attributes (such as schemaLocation, to be used next) that are part of a schema specification. These attributes can be applied to elements in instance documents to provide additional information to a schema-aware XML processor. Again, a usual convention is to use the namespace prefix xsi: for XMLSchema-instance. Step 3 (lines 3b3c): With the xsi:schemaLocation attribute, tell the schema-aware XML processor to establish the binding between the current XML document and its schema. The attribute contains a pair of values. The first value is the namespace identifier whose schemas location is identified by the second value. In our case the namespace identifier is http://any.website.net/letter and the location of the schema document is http://any.website.net/letter/letter.xsd. (In this case, it would suffice to only have letter.xsd as the second value, since the schema documents URL overlaps with the namespace identifier.) Typically, the second value will be a URL, but specialized applications can use other types of values, such as an identifier in a schema repository or a well-known schema name. If the document used more than one namespace, the xsi:schemaLocation attribute would contain multiple pairs of values (all within a single pair of quotations). Notice that the schemaLocation attribute is merely a hint. If the parser already knows about the schema types in that namespace, or has some other means of finding them, it does not have to go to the location you gave it. XML Schema defines two aspects of an XML document structure:

Chapter 6

XML and Data Representation

261

1. Content model validity, which tests whether the arrangement and embedding of tags is correct. For example, postal address tag must have nested the street, city, and postal-code tags. A country tag is optional. 2. Datatype validity, which is the ability to test whether specific units of information are of the correct type and fall within the specified legal values. For example, a postal code is a five-digit number. Data types are the classes of data values, such as string, integer, or date. Values are instances of types. There are two types of data: 1. Simple types are elements that contain data but not attributes or sub-elements. Examples of simple data values are integer or string, which do not have parts. New simple types are defined by deriving them from existing simple types (built-ins and derived). 2. Compound types are elements that allow sub-elements and/or attributes. An example is personAddressType type defined in Listing 6-7. Complex types are defined by listing the elements and/or attributes nested within them.

6.2.2

Models for Structured Content

As noted above, schema defines the content model of XML documentsthe legal building blocks of an XML document. A content model indicates what a particular element can contain. An element can contain text, other elements, a mixture of text and elements, or nothing at all. Content model defines: elements that can appear in a document attributes that can appear in a document which elements are child elements the order of child elements the multiplicity of child elements whether an element is empty or can include text data types for elements and attributes default and fixed values for elements and attributes

This section reviews the schema tools for specifying syntactic and structural constraints on document content. The next section reviews datatypes of elements and attributes, and their value constraints.

XML Schema Elements

XML Schema defines a vocabulary on its own, which is used to define other schemas. Here I provide only a brief overview of XML Schema elements that commonly appear in schema documents. The reader should look for the complete list here: http://www.w3.org/TR/2004/RECxmlschema-1-20041028/structures.html. The <schema> element defines the root element of every XML Schema.

Ivan Marsic

Rutgers University

262

Syntax of the <schema> element

<schema id=ID attributeFormDefault=qualified | unqualified

Description (attributes are optional unless stated else)

Specifies a unique ID for the element. The form for attributes declared in the target namespace of this schema. The value must be "qualified" or "unqualified". Default is "unqualified". "unqualified" indicates that attributes from the target namespace are not required to be qualified with the namespace prefix. "qualified" indicates that attributes from the target namespace must be qualified with the namespace prefix. The form for elements declared in the target namespace of this schema. The value must be "qualified" or "unqualified". Default is "unqualified". "unqualified" indicates that elements from the target namespace are not required to be qualified with the namespace prefix. "qualified" indicates that elements from the target namespace must be qualified with the namespace prefix.

elementFormDefault=qualified | unqualified

blockDefault=(#all | list of (extension | restriction | substitution)) finalDefault=(#all | list of (extension | restriction | list | union)) targetNamespace=anyURI version=token xmlns=anyURI any attributes > ((include | import | redefine | annotation), (((simpleType | complexType | group | attributeGroup) | element | attribute | notation), annotation)) </schema>

A URI reference of the namespace of this schema. Required. A URI reference that specifies one or more namespaces for use in this schema. If no prefix is assigned, the schema components of the namespace can be used with unqualified references.

Kleene operators ?, +, and are defined in Figure 6-5.

The <element> element defines an element. Its parent element can be one of the following: <schema>, <choice>, <all>, <sequence>, and <group>. Description (all attributes are optional) Syntax of the <element> element
<element id=ID name=NCName ref=QName type=QName substitutionGroup=QName default=string fixed=string form=qualified|unqualified maxOccurs=nonNegativeInteger|unbounded Specifies a name for the element. This attribute is required if the parent element is the schema element. Refers to the name of another element. This attribute cannot be used if the parent element is the schema element. Specifies either the name of a built-in data type, or the name of a simpleType or complexType element. This value is automatically assigned to the element when no other value is specified. (Can only be used if the elements content is a simple type or text only). Specifies the maximum number of times this element can occur in the parent element. The value can be any number >= 0, or if you want to

Chapter 6

XML and Data Representation

263

minOccurs=nonNegativeInteger nillable=true|false abstract=true|false block=(#all|list of (extension|restriction)) final=(#all|list of (extension|restriction)) any attributes > annotation?,((simpleType | complexType)?,(unique | key | keyref))) </element>

set no limit on the maximum number, use the value "unbounded". Default value is 1. Specifies the minimum number of times this element can occur in the parent element. The value can be any number >= 0. Default is 1.

Kleene operators ?, +, and are defined in Figure 6-5.

The <group> element is used to define a collection of elements to be used to model compound elements. Its parent element can be one of the following: <schema>, <choice>, <sequence>, <complexType>, <restriction> (both <simpleContent> and <complexContent>), <extension> (both <simpleContent> and <complexContent>). Description (all attributes are optional) Syntax of the <group> element
<group id=ID name=NCName ref=QName maxOccurs=nonNegativeInteger | unbounded minOccurs=nonNegativeInteger any attributes > (annotation?, (all | choice | sequence)) </group> Specifies a name for the group. This attribute is used only when the schema element is the parent of this group element. Name and ref attributes cannot both be present. Refers to the name of another group. Name and ref attributes cannot both be present.

The <attributeGroup> element is used to group a set of attribute declarations so that they can be incorporated as a group into complex type definitions. Description (all attributes are optional) Syntax of <attributeGroup>
<attributeGroup id=ID name=NCName ref=QName any attributes > (annotation?), ((attribute | attributeGroup), anyAttribute?)) Specifies the name of the attribute group. Name and ref attributes cannot both be present. Refers to a named attribute group. Name and ref attributes cannot both be present.

Ivan Marsic

Rutgers University

264

</attributeGroup>

The <annotation> element specifies schema comments that are used to document the schema. This element can contain two elements: the <documentation> element, meant for human consumption, and the <appinfo> element, for machine consumption.

Simple Elements
A simple element is an XML element that can contain only text. It cannot contain any other elements or attributes. However, the only text restriction is ambiguous since the text can be of many different types. It can be one of the built-in types that are included in the XML Schema definition, such as boolean, string, date, or it can be a custom type that you can define yourself as will be seen Section 6.2.3 below. You can also add restrictions (facets) to a data type in order to limit its content, and you can require the data to match a defined pattern. Examples of simple elements are <salutation> and <body> elements in Listing 6-7 above.

Groups of Elements
XML Schema enables collections of elements to be defined and named, so that the elements can be used to build up the content models of complex types. Un-named groups of elements can also be defined, and along with elements in named groups, they can be constrained to appear in the same order (sequence) as they are declared. Alternatively, they can be constrained so that only one of the elements may appear in an instance. A model group is a constraint in the form of a grammar fragment that applies to lists of element information items, such as plain text or other markup elements. There are three varieties of model group: Sequence element <sequence> (all the named elements must appear in the order listed); Conjunction element <all> (all the named elements must appear, although they can occur in any order); Disjunction element <choice> (one, and only one, of the elements listed must appear).

6.2.3

Datatypes

In XML Schema specification, a datatype is defined by: (a) Value space, which is a set of distinct values that a given datatype can assume. For example, the value space for the integer type are integer numbers in the range [4294967296, 4294967295], i.e., signed 32-bit numbers.

Chapter 6

XML and Data Representation

265

(b) Lexical space, which is a set of allowed lexical representations or literals for the datatype. For example, a float-type number 0.00125 has alternative representation as 1.25E3. Valid literals for the float type also include abbreviations for positive and negative infinity (INF) and Not a Number (NaN). (c) Facets that characterize properties of the value space, individual values, or lexical items. For example, a datatype is said to have a numeric facet if its values are conceptually quantities (in some mathematical number system). Numeric datatypes further can have a bounded facet, meaning that an upper and/or lower value is specified. For example, postal codes in the U.S. are bounded to the range [10000, 99999]. XML Schema has a set of built-in or primitive datatypes that are not defined in terms of other datatypes. We have already seen some of these, such as xsd:string which was used in Listing 6-7. More will be exposed below. Unlike these, derived datatypes are those that are defined in terms of other datatypes (either primitive types or derived ones).

Simple Types: <simpleType>

These types are atomic in that they can only contain character data and cannot have attributes or element content. Both built-in simple types and their derivations can be used in all element and attribute declarations. Simple-type definitions are used when a new data type needs to be defined, where this new type is a modification of some other existing simpleType-type. Table 6-1 shows a partial list of the Schema-defined types. There are over 40 built-in simple types and the reader should consult the XML Schema specification (see http://www.w3.org/TR/xmlschema-0/, Section 2.3) for the complete list.

Table 6-1: A partial list of primitive datatypes that are built into the XML Schema. Name string byte unsignedByte boolean short int integer long float Examples My favorite text example 128, 1, 0, 1, , 127 0, , 255 0, 1, true, false 5, 328 7, 471 2, 435 4, 123456 0, 0, INF, INF, 1E4, 1.401298464324817e45, 3.402823466385288e+38, NaN Comments

double duration dateTime

A signed byte value Derived from unsignedShort May contain either true or false, 0 or 1 Signed 16-bit integer Signed 32-bit integer Same as int Signed 64-bit integer Conforming to the IEEE 754 standard for 32bit single precision floating point number. Note the use of abbreviations for positive and negative infinity (INF), and Not a Number (NaN) Conforming to the IEEE 754 standard for 640, 0, INF, INF, 1E4, 4.9e324, 1.797e308, NaN bit double precision floating point numbers P1Y2M3DT10H30M12.3S 1 year, 2 months, 3 days, 10 hours, 30 minutes, and 12.3 seconds 1997-03-31T13:20:00.000- March 31st 1997 at 1.20pm Eastern Standard

Ivan Marsic

Rutgers University

266

05:00 date time gYear gDay QName language ID 1997-03-31 13:20:00.000, 13:20:00.000-05:00 1997 ---31 lt:sender en-GB, en-US, fr this-element this-element

Time which is 5 hours behind Coordinated Universal Time

IDREF

The g prefix signals time periods in the Gregorian calendar. the 31st day XML Namespace QName (qualified name) valid values for xml:lang as defined in XML 1.0 An attribute that identifies the element; can be any string that confirms to the rules for assigning the <element> names. IDREF attribute type; refers to an element which has the ID attribute with the same value

A straightforward use of built-in types is the direct declaration of elements and attributes that conform to them. For example, in Listing 6-7 above I declared the <signature> element and template attribute of the <letter> element, both using xsd:string built-in type:
<xsd:element name="signature" type="xsd:string"/> <xsd:attribute name="template" type="xsd:string"/>

New simple types are defined by deriving them from existing simple types (built-ins and derived). In particular, we can derive a new simple type by restricting an existing simple type, in other words, the legal range of values for the new type are a subset of the existing types range of values. We use the <simpleType> element to define and name the new simple type. We use the restriction element to indicate the existing (base) type, and to identify the facets that constrain the range of values. A complete list of facets is provided below.

Facets and Regular Expressions

We use the facets of datatypes to constrain the range of values. Suppose we wish to create a new type of integer called zipCodeType whose range of values is between 10000 and 99999 (inclusive). We base our definition on the built-in simple type integer, whose range of values also includes integers less than 10000 and greater than 99999. To define zipCodeType, we restrict the range of the integer base type by employing two facets called minInclusive and maxInclusive (to be introduced below): Listing 6-9: Example of new type definition by facets of the base type.
<xsd:simpleType name="zipCodeType"> <xsd:restriction base="xsd:integer"> <xsd:minInclusive value="10000"/> <xsd:maxInclusive value="99999"/> </xsd:restriction> </xsd:simpleType>

Table 6-2 and Table 6-3 list the facets that are applicable for built-in types. The facets identify various characteristics of the types, such as:

Chapter 6

XML and Data Representation

267

length, minLength, maxLengththe exact, minimum and maximum character length of the value patterna regular expression pattern for the value (see more below) enumerationa list of all possible values (an example given in Listing 6-10 below) whiteSpacethe rules for handling white-space in the value minExclusive, minInclusive, maxExclusive, maxInclusivethe range of numeric values that are allowed (see example in Listing 6-9 above) totalDigitsthe maximum allowed number of decimal digits in numeric values fractionDigitsthe number of decimal digits after the decimal point

As indicated in the tables, not all facets apply to all types. Table 6-2: XML Schema facets for built-in simple types. Indicated are the facets that apply to the particular type. Simple Types string base64Binary hexBinary integer positiveInteger negativeInteger nonNegativeInteger nonPositiveInteger decimal boolean time dateTime duration date Name QName anyURI ID IDREF length minLength maxLength Facets pattern enumeration whitespace

Table 6-3: XML Schema facets for built-in ordered simple types. Facets maxInclusive maxExclusive minInclusive minExclusive integer positiveInteger negativeInteger nonNegativeInteger nonPositiveInteger decimal Simple Types totalDigits fractionDigits

Ivan Marsic

Rutgers University

268

time dateTime duration date

The pattern facet shown in Table 6-2 is particularly interesting since it allows specifying a variety of constraints using regular expressions. The following example (Listing 6-10) shows how to define the datatype for representing IP addresses. This datatype has four quads, each restricted to have a value between zero and 255, i.e., [0-255].[0-255].[0-255].[0-255] Listing 6-10: Example of IP address type definition via the pattern facet.
<xsd:simpleType name="IPaddress"> <xsd:restriction base="xsd:string"> <xsd:pattern value="(([1-9]?[0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} ([1-9]?[0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])"/> </xsd:restriction> </xsd:simpleType>

Note that in the value attribute above, the regular expression has been split over three lines. This is for readability purposes only; in practice the regular expression would all be on one line. Selected regular expressions with examples are given in Table 6-4. Table 6-4: Examples of regular expressions. Regular Expression
Section \d

Example
Section 3

Regular Expression
Chapter\s\d (hi){2} there (hi\s){2} there .abc (a|b)+x

Example
Chapter followed by a blank followed by a digit hihi there hi hi there any (one) char followed by abc ax, bx, aax, bbx, abx, bax,... ax, aax, aaax aax, aaax, aaaax, ... word character (alphanumeric plus dash) followed by a space followed by a word character A string comprised of any lower and upper case letters, except "O" and "k" The period "." (Without the backward slash the period means "any character") linefeed

Chapter&#x020;\d Chapter 7 a*b b, ab, aab, aaab, ... [xyz]b xb, yb, zb a?b b, ab

a+b [a-c]x [-ac]x

ab, aab, aaab, ... a{1,3}x ax, bx, cx a{2,}x -x, ax, cx \w\s\w

[ac-]x

ax, cx, -x any non-digit char followed by x any non-digit char followed by x

[a-zA-Z-[Ok]]*

[^0-9]x

\.

\Dx

\n

Chapter 6

XML and Data Representation

269

Compound Types: <complexType>

Compound or complex types can have any kind of combination of element content, character data, and attributes. The element requires an attribute called name, which is used to refer to the <complexType> definition. The element then contains the list of sub-elements. You may have noticed that in the example schema (Listing 6-7), some attributes of the elements from Listing 6-1 were omitted for simplicity sake. For example, <salutation> could have a style attribute, with the value space defined as {"informal", "formal", "business", "other"}. To accommodate this, <salutation> should be defined as a complex type, as follows: Listing 6-11: Upgraded XML Schema for the <salutation> element. This code replaces line 9 Listing 6-7. The rest remains the same.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <xsd:element name="salutation"> <xsd:complexType> <xsd:simpleContent> <xsd:extension base="xsd:string"> <xsd:attribute name="style" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="informal"/> <xsd:enumeration value="formal"/> <xsd:enumeration value="business"/> <xsd:enumeration value="other"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> </xsd:element>

The explanation of the above listing is as follows: Line 2: Uses the <complexType> element to start the definition of a new (anonymous) type. Line 3: Uses a <simpleContent> element to indicate that the content model of the new type contains only character data and no elements. Lines 45: Derive the new type by extending the simple xsd:string type. The extension consists of adding a style attribute using attribute declaration. Line 6: The attribute style is a simpleType derived from xsd:string by restriction. Lines 712: The attribute value space is specified using the enumeration facet. The attribute value must be one of the listed salutation styles. Note that the enumeration values specified for a particular type must be unique. The content of a <complexType> is defined as follows (see also Figure 6-6): 1. Optional <annotation> (schema comments, which serve as inline documentation) 2. This must be accompanied by one of the following:

Ivan Marsic

Rutgers University

270

type name can be given by attribute name

xsd:notation xsd:simpleContent xsd:group

xsd:complexType

xsd:complexContent

xsd:sequence

xsd:choice

xsd:all

xsd:attribute

xsd:attributeGroup

xsd:anyAttribute

Figure 6-6: Structure of the <complexType> schema element. Symbols follow the notation introduced in Figure 6-5. a. <simpleContent> (which is analogous to the <simpleType> elementused to modify some other simple data type, restricting or extending it in some particular waysee example in Listing 6-11 above) b. <complexContent> (which is analogous to the <complexType> element used to create a compound element) c. In sequence, the following: i. Zero or one from the following grouping terms: 1. <group> Commonly used to declare a collection of elements that are referenced from more than one place within the same schema of by other schemas (hence, this is a global declaration). The personAddressType type in Listing 6-7 could have been done this way 2. <sequence> All the named elements must appear in the order listed 3. <choice> One, and only one, of the elements listed must appear 4. <all> All the named elements must appear, but order is not important ii. Followed by any number of either 1. <attribute> 2. <attributeGroup> iii. Then zero or one <anyAttribute> (enables attributes from a given namespace to appear in the element)

Chapter 6

XML and Data Representation

271

In the example, Listing 6-7, we used both inlined element declaration with anonymous type as well as named type, which was then used to declare an element. An element declaration can have a type attribute, or a complexType child element, but it cannot have both a type attribute and a complexType child element. The following table shows the two alternatives: Element A references the complexType foo:
<xsd:element name="A" type="foo"/> <xsd:complexType name="foo"> <xsd:sequence> <xsd:element name="B" .../> <xsd:element name="C" .../> </xsd:sequence> </xsd:complexType>

Element A has the complexType definition inlined in the element declaration:

<xsd:element name="A"> <xsd:complexType> <xsd:sequence> <xsd:element name="B" .../> <xsd:element name="C" .../> </xsd:sequence> </xsd:complexType> </xsd:element>

6.2.4

Reuse

We can roughly split up reuse mechanisms into two kinds: basic and advanced. The basic reuse mechanisms address the problem of modifying the existing assets to serve the needs that are perhaps different from what they were originally designed for. The basic reuse mechanisms in XML Schema are: Element references Content model groups Attribute groups Schema includes Schema imports

6.2.5

RELAX NG Schema Language

What we reviewed above is the World Wide Web Consortiums standard XML Schema. There are several other alternative schema languages proposed for XML. One of them is RELAX NG. Its home page (http://www.relaxng.org/) states that RELAX NG is a schema language for XML. The claims are that RELAX NG: * is simple * is easy to learn * has both an XML syntax and a compact non-XML syntax * does not change the information set of an XML document

Ivan Marsic

Rutgers University

272

* supports XML namespaces * treats attributes uniformly with elements so far as possible * has unrestricted support for unordered content * has unrestricted support for mixed content * has a solid theoretical basis * can partner with a separate datatyping language (such W3C XML Schema Datatypes)

You could write your schema in RELAX NG and use Trang (Multi-format schema converter based on RELAX NG) to convert it to XML Schema. See online at: http://www.thaiopensource.com/relaxng/trang.html

6.3 Indexing and Linking

Links in HTML documents are tagged with <A HREF="http://...">, where the value of the HREF attribute refers to a target document.

6.3.1

XPointer and Xpath

XML Pointer Language (XPointer) is based on the XML Path Language (XPath), which supports addressing into the internal structures of XML documents. XPointer allows references to elements, attributes, character strings, and other parts of XML documents. XPointer referencing works regardless of whether the referenced objects bear an explicit ID attribute (an attribute named id, such as id="section4"). It allows for traversals of a document tree and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position. XPointers operate on the tree defined by the elements and other markup constructs of an XML document. An XPointer consists of a series of location terms, each of which specifies a location, usually relative to the location specified by the prior location term. Here are some examples of location paths: child::para child::* selects the para element children of the context node selects all element children of the context node

child::text() selects all text node children of the context node child::node() selects all the children of the context node, whatever their node type attribute::name selects the name attribute of the context node attribute::* selects all the attributes of the context node

Chapter 6

XML and Data Representation

273

para *

matches any para element matches any element matches any chapter element and any appendix element

chapter|appendix olist/item

matches any item element with an olist parent

appendix//para matches any para element with an appendix ancestor element / text() matches the root node matches any text node

items/item[position()>1] matches any item element that has a items parent and that is not the first item child of its parent item[position() mod 2 = 1] odd-numbered item child of its parent @class would be true for any item element that is an

matches any class attribute (not any element that has a class attribute)

div[@class="appendix"]//p matches any p element with a div ancestor element that has a class attribute with value appendix

The following example is a combination of a URL and an XPointer and refers to the seventh child of the fourth section under the root element:
http://www.foo.com/bar.html#root().child(4,SECTION).child(7)

6.3.2

XLink

A link is an explicit relationship between two or more data objects or parts of data objects. A linking element is used to assert link existence and describe link characteristics. XML Linking Language (XLink) allows elements to be inserted into XML documents in order to create and describe links between resources. In HTML, a link is unidirectional from one resource to another and has no special meaning, except it brings up the referred document when clicked in a browser. XLink uses XML syntax to create structures that can describe the simple unidirectional hyperlinks of todays HTML as well as more sophisticated multidirectional and typed links. With XLink, a document author can do the following, among others: Associate semantics to a link by giving a role to the link. Define a link that connects more than two resources. Define a bidirectional link.

A link is an explicit relationship between two or more data objects or portions of data objects. A linking element is used to assert link existence and describe link characteristics. Linking elements are recognized based on the use of a designated attribute named xml:link. Possible values are simple and extended (as well as locator, group, and document, which identify other related types of elements). An element that includes such an attribute should be treated as a linking element of the indicated type. The following is an example similar to the HTML A link:

Ivan Marsic

Rutgers University

274

<A xml:link="simple" href="http://www.w3.org/XML/XLink/0.9"> The XLink<A>

An example of an extended link is:

<xlink:extended xmlns:xlink="http://www.w3.org/XML/XLink/0.9" role="resources" title="Web Resources" showdefault="replace" actuatedefault="user"> <xlink:locator href="http://www.xml.com" role="resource" title="XML.com"/> <xlink:locator href="http://www.mcp.com" role="resource" title="Macmillan"/> <xlink:locator href="http://www.netscape.com" role="resource" title="Netscape Communications"/> <xlink:locator href="http://www.abcnews.com" role="resource" title="ABC News"/>

Link Behavior
XLink provides behavior policies that allow link authors to signal certain intentions as to the timing and effects of link traversal. These include: Show: The show attribute is used to express a policy as to the context in which a resource that is traversed to should be displayed or processed. It may take one of three values: embed, replace, new. Actuate: The actuate attribute is used to express a policy as to when traversal of a link should occur. It may take one of two values: auto, user. Behavior: The behavior attribute is used to provide detailed behavioral instructions.

6.4 Document Transformation and XSL

If at first you don't succeed, transform your data. The law of computability applied to social sciences

As explained above, XML is not a fixed tag set (like HTML) so the tags do not carry a fixed, application-specific meaning. A generic XML processor has no idea what is meant by the XML. Because of this, a number of other standards to process the XML files are developed. Extensible Stylesheet Language (XSL) is one such standard. XML markup usually does not include formatting information. The information in an XML document may not be in the form in

Chapter 6

XML and Data Representation

275

which it is desired to be presented. There must be something in addition to the XML document that provides information on how to present or otherwise process the XML. XSL transforms and translates XML data from one XML format into another. It is designed to help browsers and other applications display XML. Stated simply, a style sheet contains instructions that tell a processor (such as a Web browser, print composition engine, or document reader) how to translate the logical structure of a source document into a presentational structure. The XML/XSL relationship is reminiscent of the Model-View-Controller design pattern [Gamma et al., 1995], which separates the core data from the way it gets visualized. Likewise, XSL enables us to separate the view from the actual data represented in XML. This has following advantages: Reuse of data: When the data is separate you do not need to transform the actual data to represent it in some other form. We can just use a different view of the data. Multiple output formats: When view is separate from the data we can have multiple output formats for the same data e.g. the same XML file can be viewed using XSL as VRML, HTML, XML (of some other form) Readers preferences: The view of the same XML file can be customized with the preferences of the user. Standardized styles: Within one application domain there can be certain standard styles which are common throughout the developer community. Freedom from content authors: A person not so good at presentation can just write the data and have a good presenter to decide on how to present the data. Different ways of displaying an XML files are shown in Figure 6-7.

XSL can act as a translator, because XSL can translate XML documents that comply with two different XML schemas. XSL is an unfortunate name, since you may think it deals only with stylesheets. That is not true, it is much more general and as I said, XSL can translate any XML document to any other XML document.

Ivan Marsic

Rutgers University

276

XSL

General form of a template rule:

<xsl:template match="pattern"> ... action ... </xsl:template>

XML

Transformation Engine (XSL Processor)

HTML / text / XML

Figure 6-7. How XSL transformation works.

XSL Example
The following example shows an original XML document transformed to an HTML document.

Listing 6-12: Example XSL document. Original XML source:

1 2 <?xml version='1.0'?> <para>This is a <emphasis>test</emphasis>.</para>

XSL stylesheet:
1 2 3 4 5 6 7 8 9 10 11 12 13 <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Format" version="1.0"> <xsl:template match="para"> <p><xsl:apply-templates/></p> </xsl:template> <xsl:template match="emphasis"> <i><xsl:apply-templates/></i> </xsl:template> </xsl:stylesheet>

Resultant HTML source:

1 2 <?xml version="1.0" encoding="utf-8"?> <p>This is a <i>test</i>.</p>

XGMML (eXtensible Graph Markup and Modeling Language) 1.0 Draft http://www.cs.rpi.edu/~puninj/XGMML/draft-xgmml.html

Chapter 6

XML and Data Representation

277

"Mark Pilgrim returns with his latest Dive into XML column, "XML on the Web Has Failed," claiming that XML on the Web has failed miserably, utterly, and completely. Is Mark right or wrong? You be the judge." http://www.xml.com/pub/a/2004/07/21/dive.html

6.5 Summary and Bibliographical Notes

As a historical footnote, XML is derived from SGML (Standard Generalized Markup Language), which is a federal (FIPS 152) and international (ISO 8879) standard for identifying the structure and content of documents.

I have no intention of providing a complete coverage of XML since that would require more than a single book and would get us lost in the mind numbing number of details. My main focus is on the basic concepts and providing enough details to support meaningful discussion. I do not expect that anybody would use this text as an XML reference. The reader interested in further details should consult the following and other sources. XML is defined by the W3C in a number of related specifications available here: http://www.w3.org/TR/. A great source of information on XML is http://www.xml.com/. The standard information about HTTP is available here: http://www.w3.org/Protocols/ HTML standard information is available here: http://www.w3.org/MarkUp/ XML Tutorial online at: http://www.w3schools.com/xml/default.asp

Reference [Lee & Chu, 2000] reviews several alternative XML schema languages. A book by Eric van der Vlist, RELAX NG, OReilly & Associates, is available online at: http://books.xmlschemata.org/relaxng/page1.html .

Ivan Marsic

Rutgers University

278

Problems
Problem 6.1

Problem 6.2
Write the XML Schema that defines the production rules for the instance document shown in Listing 6-13 below. The parameters are specified as follows. Possible values for the attribute student status are full time and part time and it is required that this attribute appears. The student identification number must be exactly 9 digits long and its 4th and 5th digits must always be a zero ( 00 ). (According to the US Social Security Administration, a number with a zero in the 4th and 5th digits will never be assigned as a persons SSN. Hence, you can easily distinguish the difference between the student id and the SSN by scanning the 4th and 5th digits.) The school number must be a two-digit number (including numbers with the first digit equal to zero). The graduation class field should allow only Gregorian calendar years. The curriculum number must be a three-digit number between 100 and 999. The student grade field is optional, but when present it can contain only one of the following values: A, B+, B, C+, C, D, and F. All elements are required, unless stated otherwise. As for the non-specified parameters, make your own (reasonable) assumptions. Write down any assumptions you make. Listing 6-13: Instance XML document containing a class roster.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 <?xml version="1.0" encoding="UTF-8"?> <!-- ***** associate here your schema with this document ***** --> <class-roster> <class-name> Introduction to Software Engineering </class-name> <index> 61202 </index> <semester> Spring 2006 </semester> <enrollment> 58 </enrollment> <student status="full-time"> <student-id> 201000324 </student-id> <name> <first-name> Jane </first-name> <last-name> Doe </last-name> </name> <school-number> 14 </school-number> <graduation-class> 2006 </graduation-class> <curriculum> 332 </curriculum> <grade> A </grade>

Chapter 6

XML and Data Representation

279

18 19 20 21 22

</student> <student status="part-time"> ... </student> </class-roster>

Problem 6.3

Software Components

Chapter 7

Contents
The Organism Principle: When a system evolves to become more complex, this always involves a compromise: if its parts become too separate, then the systems abilities will be limitedbut if there are too many interconnections, then each change in one part will disrupt many others. Marvin Minsky, The Emotion Machine

7.1 Components, Ports, and Events

7.1.1 7.1.2 7.1.3 7.1.4 7.1.5 7.1.6

Software engineers have always envied hardware engineers for their successful standardization of hardware design and the power of integration and reusability achieved by the abstraction of VLSI chips. There have been many attempts in the past to bring such standardization to software design. Recently, these seem to be achieving some success, most probably because the level of knowledge in software engineering has achieved the needed threshold. There is currently a strong software industry trend towards standardizing software development through software components. Components are reusable pieces of software. Components can be GUI widgets, non-visual functions and services, applets or large-scale applications. Each component can be built by different developers at separate times. Components enable rapid development using third party software: independent components are used without modifications as building blocks to form composite applications. Components can be composed into: Composite components Applets (small client-side applications) Applications Servlets (small server-side applications)

7.2 JavaBeans: Interaction with Components

7.2.1 Property Access 7.2.2 Event Firing 7.2.3 Custom Methods 7.2.4

7.3 Computational Reflection

7.3.1 Run-Time Type Identification 7.3.2 Reification 7.3.3 Automatic Component Binding 7.3.4 7.2.3

7.4 State Persistence for Transport

7.4.1 7.4.2 7.4.3 7.4.4

7.5 A Component Framework

7.5.1 Port Interconnections 7.5.2 7.5.3 7.5.4

7.6
7.6.1 7.6.2 7.6.3

7.7 Summary and Bibliographical Notes Problems

Although a single class may not be a useful unit of reuse, a component that packages a number of services can be. Components enable medium-grained reuse. The composition can be done in visual development tools, since the components expose their features to a builder tool. A builder tool that lets you:

280

Chapter 7

Software Components

281

Graphically assemble the components into more complex components or applications Edit the properties of components Specify how information in a component is to be propagated to other components

The component developer has to follow specific naming conventions (design pattern), which help standardize the interaction with the component. In this way the builder tool can automatically detect the components inputs and outputs and present them visually. If we visualize a bean as an integrated circuit or a chip, the interaction methods can be visualized as the pins on the chip. Two major component architectures are JavaBeans from Sun [Sun Microsystems, JavBeans] and ActiveX controls from Microsoft [Denning, 1997]. Here I first review the JavaBeans component model, which is a part of the Java Development Kit version 1.1 or higher. JavaBeans component model is a specification standard, not an implementation in a programming language. There is not a class or interface in Java called Bean. Basically, any class can be a beanthe bean developer just has to follow a set of design patterns, which are essentially guidelines for naming the methods to interact with the bean. Software components, as any other software creation, comprise state and behavior. Two key issues in component development are How to interact with a component How to transfer a components state from one machine to another

Programming business logic of reusable components is the same as with any other software objects and thus it is not of concern in a component standard.

7.1 Components, Ports, and Events

Before software can be reusable it first has to be usable. Ralph Johnson

The hardware-software component analogy is illustrated in Figure 7-1. Component communicates with the rest of the world only via its ports using events. This simplification and uniformity of the component model is promoted as the main reason for introducing components as opposed to software objects. Objects succeeded in encapsulation of state and behavior (see Section 1.4), but have not had much success on the issue of reuse. It is claimed that the main reason for this is that object interconnections are often concealed and difficult to identify. We can easily determine the entry points of objects, i.e., the points through which other objects invoke the given object, which are its methods for well-designed objects. However, it is difficult to pinpoint the exit points of objectsthe points through which the object invokes the other objectswithout carefully examining the source code. Consider the following example (in Java):
class MyClass { ...

Ivan Marsic

Rutgers University

282
AMPLIFIER NO. 2 NONINV OUT- INV PUT INPUT INPUT

VCC+

14

13

12

11

10

Component

Port

OUT- INV NON- VCC PUT INPUT INV INPUT AMPLIFIER NO. 1

(a)

(b)

(c)

Figure 7-1. Hardware analogy for software component abstraction. (a) Software component corresponds to a hardware chip. (b) A component has attached ports (pins), each with a distinctive label. (c) Events or signals arriving at the ports are processed within the component and the results may be output on different ports.
public void doSomething(AnotherClass obj1) { ... obj1.getObj2().callMethod(args); ... } }

Here, the method getObj2() returns an object of a different class, which we would not know that is being involved without careful code examination. Hence the importance of enforcing uniform style for getting into and out of components, i.e., via their ports.

7.2 JavaBeans: Interaction with Components

The simplest thing to do with a software component is to retrieve its state or alter it by explicitly setting the new state or invoking a behavior of the component. Reusable software components are usually shipped around in a compiled code, rather than in source code. Given a compiled component (bytecode or binary code), the goal is to uncover its public methods in order to be able to interact with it. The process of discovering the features of a class is known as introspection. The bean developer can help the introspection process in two ways: Implicitly, by adhering to certain conventions (design patterns) in writing the code for a Java bean Explicitly, by specifying explicit additional information about the bean

Chapter 7

Software Components

283

The second way should be used in case bean contains interaction methods that do not follow the design patterns. Related to introspection is reflection, the support Java provides for examining type information at run time. Given an object or class name, you can use the class Class to discover: The fields of the class Constructors Methods Other properties (class name, isPrimitive, etc.)

The reader may wonder why anyone would want to write a program that does this; why not look up the needed information when the program is written? Why wait until run time? The answer is that this capability allows the other applications to discover the way to interact with a bean that was developed by a third party. Reflection is used to gain information about components, but the component developer is allowed to specify more information to help with characterizing the component.

7.2.1

Property Access

Properties define the beans appearance and behavior characteristics. For properties that need to be exposed, the developer must provide: Setter method void set<PropertyName>(Type newvalue) only property, e.g., password, or Getter method Type get<PropertyName>() Both setter and getter // read-write property. // write-

// read-only property, or

In addition to naming the accessor methods according to these conventions, the developer may also provide property editors for certain properties. For example, to a property may determine the beans background color. The user may enter the value for this property as a hexadecimal number 1b8fc0, but it is difficult or impossible for the user to visualize how this color15 looks. Instead, the developer may supply a graphical color chooser for the property editor, which is much more convenient for the user.

7.2.2

Event Firing

The delegation-based event model was introduced with the JavaBeans framework [SunJavaBeans]. In this model, there is no central dispatcher of events; every component that generates events dispatches its own events as they happen. The model is a derivative of the Publisher-Subscriber pattern. Events are identified by their class instead of their ID and are either propagated or delegated from an event source to an event listener.

15

In case you are looking at a black-and-white print, the background color around the text is magenta.

Ivan Marsic

Rutgers University

284

According to the delegation model, whenever an event for which an object declared itself as a source gets generated, the event is multicast to all the registered event listeners. The source object delegates of fires the events to the set of listeners by invoking a method on the listeners and passing the corresponding event object. Only objects interested in a particular event need to deal with the event and no super-event handler is required. This is also a better way of passing events to distributed objects. EventSource Any object can declare itself as a source of certain types of events. An event source has to either follow standard beans design patterns when giving names to the methods or use the BeanInfo class to declare itself as a source of certain events. When the source wishes to delegate a specific event type, it must first define a set of methods that enable listener(s) to register with the source. These methods take the form of set<EventType>Listener for unicast and/or add<EventType>Listener for multicast delegation. [The source must also provide the methods for the listeners de-register.] EventListener An object can register itself as a listener of a specific type of events originating from an event source. A listener object should implement the <EventType>Listener interface for that event type, which inherits from the generic java.util.EventListener interface. The Listener interface is typically defined only by few methods, which makes it easy to implement the interface.

7.2.3

Custom Methods

In addition to the information a builder tool can discover from the beans class definition through reflection, the bean developer can provide it with explicit additional information. A bean can be customized for a specific application either programmatically, through Java code, or visually, through GUI interfaces hosted by application builder tools. In the former case, the developer specifies additional information by providing a BeanInfo object. In the latter case, the developer can provide customized dialog boxes and editing tools with sophisticated controls. These customization tools are called property editors and customizers, and they are packaged as part of the bean, by providing the PropertyEditor and Customizer classes. The BeanInfo class should be named as <BeanName>BeanInfo, for example, for the Foo bean the BeanInfo class should be named FooBeanInfo.
class FooBeanInfo extends SimpleBeanInfo { : :

with methods:
getBeanDescriptor() getIcon() getMethodDescriptors() getPropertyDescriptors() // // // // has for for can class and customizer displaying the bean in the palette providing more information than be gained through reflection alone

A property descriptor can provide a PropertyEditor, in case the developer does not want to use the standard property editor for that property type (or there is not one available). In addition, the developer can provide a Customizer in the bean descriptor. Customizers are used to customize the entire bean, not just a property and they are not limited to customizing

Chapter 7

Software Components

285

Metadata

Introspection

Reification

Data

Figure 7-2: Computational reflection consists of two phases: (i) an introspection phase, where data is analyzed to produce suitable metadata, and (ii) a reification phase, where changes in the metadata alter the original behavior of the data it represents. properties. There is no design pattern for Customizers. You must use the BeanInfo to use a customizer and you need to use the BeanDescriptor constructor to specify the customizer class. More information about bean customization is available in [Johnson, 1997].

7.3 Computational Reflection

Computational reflection is a technique that allows a system to maintain information about itself (meta-information) and use this information to change its behavior (adapt). As shown in Figure 7-2, computational reflection refers to the capability to introspect and represent meta-level information about data or programs, to analyze and potentially modify the meta-level representation of the data, and finally to reify such changes in the metadata so that the original data or programs behave differently. It should be noted that the notion of data is universal in that it includes data structures in a program used in the source code. This is achieved by processing in two well-defined levels: functional level (also known as base level or application level) and management (or meta) level. Aspects of the base level are represented as objects in the meta-level, in a process known as reification (see below). Meta-level architectures are discussed in Section 2.2 (??) and reflective languages in Section 2.3. Finally, Section 2.4 shows the use of computational reflection in the structuring and implementation of system-oriented mechanisms. http://cliki.tunes.org/Reflection

Ivan Marsic

Rutgers University

286

7.3.1

Run-Time Type Identification

If two processes communicate externally to send and receive data, what happens when the data being sent is not just a primitive or an object whose type is known by the receiving process? In other words, what happens if we receive an object but do not know anything about itwhat instance variables and methods it has, etc. Another way to pose the question: What can we find out about the type of an object at run-time? A simple way to solve this problem is to check for all possible objects using instanceof, the operator that lets you test at run-time, whether or not an object is of a given type. A more advanced way is supported by the java.lang.reflect package, which lets you find out almost anything you want to know about an objects class at run-time. An important class for reflection is the class Class, which at first may sound confusing. Each instance of the class Class encapsulates the information about a particular class or interface. There is one such object for each class or interface loaded into the JVM. There are two ways to get an instance of class Class from within a running program: 1. Ask for it by name using the static method forName():
Class fooClass = Class.forName("Foo");

This method will return the Class object that describes the class Foo 2. Ask an instance of any Object for its class:
Foo f = new Foo(); Class fooClass = f.getClass();

As a side note, this construct is legal:

Class classClass = Class.forName("Class");

It returns back the instance of Class that describes the class Class. Once you have a Class object, you can call methods on it to find out information about the class. None of the methods are mutators, so you cannot change the class at run-time. However, you can use it to create new instance of a class, and to call methods on any instance. Some of the methods available in class Class are:
Constructor getConstructor(Class[] paramTypes); Constructor[] getConstructors(); Field getField(String name); Field[] getFields(); Method getMethod(String name, Class[] paramTypes); Method[] getMethods(); boolean isInstance(Object obj); boolean isPrimitive(); String getName();

Chapter 7

Software Components

287

caller

kernel

op : Operation

: MetaObject

obj : Object

res : Result

method(arg) create(obj, method, arg) op handle(op)

method(arg) result create(op, result) res handle(res) result

Figure 7-3. Reifying an operation. See text for explanation.

String toString();

The return types Constructor, Field, and Method are defined in the package java.lang.reflect.

7.3.2

Reification

For the meta-level to be able to reflect on several objects, especially if they are instances of different classes, it must be given information regarding the internal structure of objects. This meta-level object must be able to find out what are the methods implemented by an object, as well as the fields (attributes) defined by this object. Such base-level representation, that is available for the meta-level, is called structural meta-information. The representation, in form of objects, of abstract language concepts, such as classes and methods, is called reification. Base-level behavior, however, cannot be completely modeled by reifying only structural aspects of objects. Interactions between objects must also be materialized as objects, so that meta-level objects can inspect and possibly alter them. This is achieved by intercepting base-level operations such as method invocations, field value inquiries or assignments, creating operation objects that represent them, and transferring control to the meta level, as shown in Figure 7-3. In addition to receiving reified base-level operations from the reflective kernel, meta-level objects should also be able to create operation objects, and this should be reflected in the base level as the execution of such operations. A reflective kernel is responsible for implementing an interception mechanism. The method invocation is reified as an operation object and passed for the callees meta-object to reflect upon (handle). Eventually, the meta-object requests the kernel to deliver the operation to the callees replication object, by returning control (as in the diagram) or performing some special meta-level action. Finally, the result of the operation is reified and presented to the meta-object.

Ivan Marsic

Rutgers University

288

Show example of reflection using DISCIPLE Commands in Manifold Reflection enables dynamic (run-time) evolution of programming systems, transforming programs statically (at compile-time) to add and manage such features as concurrency, distribution, persistence, or object systems, or allowing expert systems to reason about and adapt their own behavior. In a reflective application, the base level implements the main functionality of an application, while the meta level is usually reserved for the implementation of management requirements, such as persistence [28,34], location transparency [26], replication [8,18], fault tolerance [1,2,9,10] and atomic actions [35,37]. Reflection has also been shown to be useful in the development of distributed systems [6,20,36,40,41] and for simplifying library protocols [38]. http://www.dcc.unicamp.br/~oliva/guarana/docs/design-html/node6.html#transparency

A recent small project in Squeak by Henrik Gedenryd to develop a "Universal Composition" system for programs. It essentially involves a graph of meta-objects describing sourcecomposition operations which can be eagerly or lazily (statically or dynamically) driven, resulting in partial evaluation or forms of dynamic composition such as Aspect-Oriented Programming (AOP).

7.3.3

Automatic Component Binding

Components can be seen as pieces of a jigsaw puzzle, like molecular bindingcertain molecule can bind only a molecule of a corresponding type.

7.4 State Persistence for Transport

A class is defined by the Java bytecode and this is all that is necessary to create a fresh new instance of the class. As the new instance (object) interacts with their objects, its state changes. The variables assume certain values. If we want a new instance resume from this state rather than from the fresh (initial) state, we need a mechanism to extract the object state. The mechanism is known as object serialization or in the CORBA jargon it is called object externalization [OMGCORBA-Services]. Object serialization process transforms the object graph structure into a linear sequence of bytes, essentially a byte array. The array can be stored on a physical support or sent over the network. The object that can be serialized should implement the interface java.io.Serializable. The object essentially implements the methods writeObject() and readObject(). These methods define how to convert the component attributes, which represented by programmerdefined data types, to a one-dimensional bytestream.

When restoring the object, we need to have its class (bytecode) because class definition is not stored in the serialized state. If the receiving process does not know the object's class, it will

Chapter 7

Software Components

289

throw the java.io.SerializationError exception. This may be a problem if we are sending the object to a server which is running all the time and cannot load new classes, so its class loader cannot know about the newly defined class. The solution is to use the method:
byte[] getBytes();

which is available on every java.lang.Object object, i.e., on every Java object. The method returns a byte arraya primitive data type, which can be used by the server to reconstruct the object there. JAR file contains: Manifest file Classes (next to the class name, there is a Boolean variable bean which can be true or false Bean customizers

Beans provide for a form of state migration since the bean state can be canned (serialized) and restored on a remote machine (unlike an applet which always starts in an initial state after landing on a remote machine). However, this is not object migration since the execution state (program counters for all threads) would need to be suspended and resumed. Persistency is more meant to preserve the state that resulted from external entities interacting with the bean, rather than the state of the execution, which would be possible to resume on another machine.

7.5 A Component Framework

All parts should go together without forcing. You must remember that the parts you are reassembling were disassembled by you. Therefore, if you cant get them together again, there must be a reason. By all means, do not use a hammer. IBM maintenance manual, 1925

Here I present a component framework that I designed, which is inspired by several component frameworks existing in research laboratories. Compared to JavaBeans, this framework is more radical in enforcing the component encapsulation and uniformity of communication with it.

7.5.1

Port Interconnections

Options for component wiring are illustrated in Figure 7-4. The ports of different components can be connected directly, one-on-one. In the simplest case, output port of a component directly connects to an input port of another component. Another useful analogy is wire, which is a broadcast medium to which multiple ports can be connected. Similar effect could be achieved by the Publisher-Subscriber pattern (see Section 4.1 above), but the Wire abstraction appears to be more elegant in the context of components and ports. In the spirit of object-oriented encapsulation, components as defined here share nothingthey have no shared state variables. The communication is entirely via messages. Of course,

Ivan Marsic

Rutgers University

290

E G

C
(a)

F
Wire Composite component Prefix ports

(b)

(c)

Figure 7-4. Options for wiring the ports. (a) Component ports can be directly soldered one-on-one. (b) The abstraction of wire provides a broadcast medium where the event from any output connected to the wire appears on all input ports connected to the same wire. (c) Prefix ports are used in wiring composite components. communication via ports is limited to the inter-component communication. Components contain one or more objects, which mutually communicate via regular method calls. Similarly, components make calls to the runtime environment and vice versa, via method calls. The only requirement that is enforced is that components communicate with each other via ports only. Components can be composed into more complex, composite components, as in Figure 7-1(c), where each operational amplifier within the chip could be a separate component. Composing components is illustrated in Figure 7-4(c), where component H contains component I. Notice that one of the output ports of component G connects to an input port of component H which is directly connected to an input port of component I. Regular input port cannot be connected to another input port. Similar is true for output ports. To support forming chains of ports of the same type, we introduce a prefix port sub-type, shown in Figure 7-4(c). Typical event communication and processing in a single-threaded system is illustrated in the sequence diagram in Figure 7-5. In this example, component A receives Event 1 on the input port a1, processes it and generates event 2 on the output port a2. This event is received and processed by component B. The dashed lines at the bottom of the figure indicate how the thread returns after this sequential processing is completed. All components and ports are named and addressable using a Unix-type path. For example, full path format for a port on a nested component is as: container_component_name/inner_component_name@port_name Component names are separated by forward slashes (/) and the port name is preceded by at sign (@). Thus, the components and their ports form a tree structure.

Design Issues
It was debated whether to strictly enforce the Port model for communicating with Components. Currently, actions that require computation go via Ports. Conversely, access to state variables (component properties) is via setProperty()/getProperty() methods. So, if component has a handle/reference to another component (which normally should not happen!), it can invoke these methods. Of course, the state access could also go over the Ports, but convenience was

Chapter 7

Software Components

291

a1 : PortIn receive(Event1)

A : Component

a2 : PortOut

b1 : PortIn

B : Component

process(Event1)

send(Event2)

receive(Event2)

process(Event2)

Figure 7-5. Typical event communication and processing in a single-threaded system. preferred over compliance. Further deliberation may be warranted to evaluate the merits and hazards of the current solution. Another issue is, what if, in Figure 7-5, component A needs some return value from component B? This could probably be achieved by connecting Bs output port to As another input port, but is this the most elegant/efficient solution?

7.5.2

Levels of Abstraction

A key question with components is the right size, the level of abstraction. Low level of specialization provides high generality and reusability, but also low functionality thus resulting in productivity gain. Cf. Lego blocks: Although it is possible to build anything using the simplest rectangular blocks, Lego nevertheless provides specialized pre-made pieces for certain purposes. The point is not whether anything can be built with universal components; the point is whether it is cost effective to do so.

Recall Example 3.1 (??) about the simplified domain model of the virtual biology lab (described at the book website, given in Preface). We compared the solution presented in Problem 2.12 that uses abstract objects modeled after the physical objects against a simplified solution that uses only abstract geometric figures (lines, circles, polygons, etc.). True, the simplified model is not adequate because classes Cell or Nucleus have relatively strong semantic meaning, whereas class Circle can stand for both of these and many other things. However, one may wonder whether we need to represent every detail in the problem domain by a different class. Consider human bodies composed of cellsthere are only 255 or so specialized sorts of cell [Alberts, et al., 1989]. For comparison, Java libraries have thousands different classes. Of course, each cell has many complex elements. One may wonder whether it is possible to have a similar, biologically inspired, hierarchical abstraction and composition of functions. UML packages contain classes, but they

Ivan Marsic

Rutgers University

292

are not functional abstraction. Work on software architectures is in early stages and may eventually offer the path for component abstraction.

7.6 Summary and Bibliographical Notes

Cite a book on Java Beans.

Computational reflection was introduced in [Smith, 1982]. A review is available in [Maes, 1987]. The component design presented in Section 7.5 is derived from the current literature, mostly the references [Allan et al., 2002; Bramley et al., 2000; Chen & Szymanski, 2001; Hou et al., 2005; Szymanski & Chen, 2002; Tyan et al., 2005]. Additional information is available from the Common Component Architecture (CCA) Forum at http://www.cca-forum.org/.

Problems

Web Services

Chapter 8

Contents
A Web service is a software function or resource offered as a service; remotely accessed over the web; and, has programmatic access using standard protocols. A Web service is an interface that describes a collection of operations that are network accessible through standardized XML messaging. Web services fulfill a specific task or a set of tasks. A Web service is described using a standard, formal XML notion, called its service description that provides all the details necessary to interact with the service including message formats, transport protocols and location. While there are several definitions available it can be broadly agreed that a Web service is a platform and implementation independent software component that can be, Described using a service description language Published to a registry of services Discovered through a standard mechanism Invoked through a declared API, usually over a network Composed with other services
8.1 Service Oriented Architecture
8.1.1 8.1.2 8.1.3 8.1.4 8.1.5 8.1.6 8.1.7

8.2 SOAP Communication Protocol

8.2.1 8.2.2 8.2.3 8.2.4 The SOAP Message Format The SOAP Section 5 Encoding SOAP Communication Styles Binding SOAP to a Transport Protocol

8.3 WSDL for Web Service Description

8.3.1 The WSDL 2.0 Building Blocks 8.3.2 Defining a Web Services Abstract Interface 8.3.3 Binding a Web Service Implementation 8.3.4 Using WSDL to Generate SOAP Binding 8.3.5 Non-functional Descriptions and Beyond WSDL

8.4 UDDI for Service Discovery and Integration

8.4.1 8.4.2 8.4.3 8.4.4

8.5 Developing Web Services with Axis

8.5.1 Server-side Development with Axis 8.5.2 Client-side Development with Axis 8.5.3 8.5.4

Web services are characterized as loose coupling of applicationsclients and service providers need not be known a priori. The underlying mechanism that enables this is: publish-find-bind, or sometimes called find-bind-execute. The application can be developed without having to code or compile in what services you need. Similarly, when service provider deploys a service, it does not need to know its clients. In summary, (1) Service publishes its description; (2) Client finds service based on description; and, (3) Client binds itself to the service.

8.6 OMG Reusable Asset Specification

8.6.1 8.6.2 8.6.3

8.7 Summary and Bibliographical Notes Problems

293

Ivan Marsic

Rutgers University

294

The only common thing across Web services is the data format (ontology). There is no APIs involved, no remote service invocation. Each method is a different service; invocation is governed by the service contract. A web site (portal) provides a collection of Web services.

Tom Gruber, What is an Ontology? Online at: http://www-ksl.stanford.edu/kst/what-is-anontology.html A closer look at Microsoft's new Web services platform, "Indigo," from the same source. http://www.eweek.com/article2/0,1759,1763162,00.asp

Web services essentially mean using SOAP Remote Procedure Call. Web services function in the information pull mode. The reason for this is firewalls, which allow only pulling of the information with Web services. Although HTTP 1.1 allows keeping state on the server, it is still a pull mode of communication. The pull mode is not appropriate for distributing real-time information; for this we need the push mode. If we want to use Web services in the push mode, we have two options: 1. Use tricks 2. Web services pushing unsolicited notification In the first case, we have an independent broker to which the clients that are to receive notifications should connect. The broker is in the trusted part of the network and it helps to push information to the client of the Web service. In the second case, the Web service standard needs to be modified to allow pushing information from the server. An important issue that needs to be considered is whether this capability can lead to denial-of-service attacks. Peer-to-peer communication is also an issue because of firewalls. So, What the Heck Are Web Services? http://www.businessweek.com/technology/content/feb2005/tc2005028_8000_tc203.htm A "Milestone" for Web Services http://www.businessweek.com/technology/content/feb2005/tc2005028_4104_tc203.htm GENERAL: http://www.businessweek.com/technology/index.html Web Services Leaders Submit Key Messaging Spec: A group of leading Web services proponents, including Microsoft and Sun Microsystems, on Tuesday announced the joint submission of a key Web services specification to the World Wide Web Consortium (W3C). http://www.eweek.com/article2/0,1759,1634158,00.asp Read how this could signal a turning point in the battle over Web services specifications intellectual property rights.

Chapter 8

Web Services

295

Pu 1.

ter gis e /R lish b

2. Fin d/ S ea rc

Discovery Agency / Registry

Service Description

3. Bind/Use Service Provider Service Customer

Figure 8-1: Service Oriented Architecturecomponents and relationships.

8.1 Service Oriented Architecture

Service Oriented Architecture (SOA) is an architectural style whose goal is to achieve loose coupling among interacting software agents. Typically, service oriented architecture contains three components (see Figure 8-1): a service provider, a service customer, and a service registry. A service is a unit of work done by a service provider to achieve desired end results for a service customer. Both provider and customer are roles played by software agents on behalf of their users. SOA is a simple but powerful concept which can be applied to describe a wide variety of Web service implementations. A service provider creates a service description, publishes that service description to one or more service registries and receives Web service invocation requests from one or more service consumers. It is important to note that the service provider publishes the description of how the service behaves and not the service code. This service description informs the service customer everything it needs to know in order to properly understand and invoke the Web service. More information on service description is available in Section 8.3 below. A service customer finds service descriptions published to one or more service registries and use service descriptions to bind or to invoke Web services hosted by service providers.

Ivan Marsic

Rutgers University

296

discovery agency : UDDI, WSIL Delphi method facilitator : Service Requestor : SOAP Runtime http : Transport http : Transport forecaster description : WSDL create obtain publish initialize

data tracking and machine learning : Backend stock forecast expert : Service Provider : SOAP Runtime

find

get recommendation invoke do forecast

Figure 8-2: Web services dynamic interactions.

8.2 SOAP Communication Protocol

SOAP (Simple Object Access Protocol or Service Oriented Architecture Protocol) is the communication protocol for Web services. It is intended for exchanging structured information (based on XML) and is relatively simple (lightweight). Most commonly it runs over HTTP (Appendix C), but it can run over a variety of underlying protocols. It has been designed to be independent of any particular programming model and other implementation-specific semantics. A key advantage of SOAP is that, because it is XML based, it is programming-language, platform, and hardware independent. SOAP, as any other communication protocol, governs how communication happens and how data is represented on the wire. The SOAP framework is an implementation of the Broker design pattern (Section 5.4) and there are many similarities between SOAP and Java RMI (or CORBA). This section describes SOAP version 1.2, which is the current SOAP specification. The older SOAP version 1.1 is somewhat different. SOAP defines the following pieces of information, which we will look at in turn: The way the XML message is structured The conventions representing a remote procedure call in that XML message

Chapter 8

Web Services

297

SOAP envelope SOAP header header block

<Envelope> <Header> header blocks </Header> <Body>

Identifies message as a SOAP message (required) Processing instructions Context information (optional) Actual message content (required) Arbitrary content (optional)

SOAP body body block

body blocks </Body> attachment blocks </Envelope>

attachment block

Figure 8-3: Schematic representation of a SOAP message. Highlighted are the required elements. A binding to HTTP, to ensure that the XML message is transported correctly The conventions for conveying an error in message processing back to the sender

8.2.1

The SOAP Message Format

A unit of communication in SOAP is a message. A SOAP message is an ordinary XML document containing the following elements (Figure 8-3): A required Envelope element that identifies the XML document as a SOAP message An optional Header element that contains the message header information; can include any number of header blocks (simply referred to as headers); used to pass additional processing or control information (e.g., authentication, information related to transaction control, quality of service, and service billing and accounting-related data) A required Body element that contains the remote method call or response information; all immediate children of the Body element are body blocks (typically referred to simply as bodies) An optional Fault element that provides information about errors that occurred while processing the message

SOAP messages are encoded using XML and must not contain DTD references or XML processing instructions. Figure 8-4 illustrates the detailed schema for SOAP messages using the notation introduced in Figure 6-5. If a header is present in the message, it must be the first immediate child of the Envelope element. The Body element either directly follows the Header element or must be the first immediate child of the Envelope element if no header is present. Because the root element Envelope is uniquely identified by its namespace, it allows processing tools to immediately determine whether a given XML document is a SOAP message. The main information the sender wants to transmit to the receiver should be in the body of the message. Any additional information needed for intermediate processing or added-value services (e.g., authentication, security, transaction control, or tracing and auditing) goes into the header. This is the common approach for communication protocols. The header contains information that

Ivan Marsic

Rutgers University

298

Envelope
soap-env:Envelope

Header

soap-env:Header

soap-env:Header

? ?

##other:any

soap-env:Body

##other:anyAttribute

##other:any Body

Global attributes:
soap-env:mustUnderstand

soap-env:Body

? ?

##other:any

Fault
soap-env:Fault

##other:anyAttribute

soap-env:role

Code Reason

soap-env:encodingStyle

soap-env:relay

?
Node

?
Role

?
Detail

Figure 8-4: The XML schema for SOAP messages. The graphical notation is given in Figure 6-5. (SOAP version 1.2 schema definition available at: http://www.w3.org/2003/05/soap-envelope). can be used by intermediate nodes along the SOAP message path. The payload or body is the actual message being conveyed. This is the reason why the header is optional. Each of the SOAP elements Envelope, Header, or Body can include arbitrary number of <any> elements. Recall that the <any> element enables us to extend the XML document with elements not specified by the schema. Its namespace is indicated as ##other, which implies elements from any namespace that is not the namespace of the parent element, that is, soapenv. An example SOAP message containing a SOAP header block and a SOAP body is given as: Listing 8-1: Example of a SOAP message.
1 <soap-env:Envelope 2 xmlns:soap-env="http://www.w3.org/2003/05/soap-envelope" 3 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 4 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 5 <soap-env:Header> 6 <ac:alertcontrol xmlns:ac="http://example.org/alertcontrol" 7 soap-env:mustUnderstand="1"> 8 <ac:priority>high</ac:priority> 9 <ac:expires>2006-22-00T14:00:00-05:00</ac:expires> 10 </ac:alertcontrol> 11 </soap-env:Header> 12 <soap-env:Body> 13 <a:notify xmlns:a="http://example.org/alert"> 14 <a:note xsi:type="xsd:string">

Chapter 8

Web Services

299

15 Reminder: meeting today at 11AM in Rm.601 16 </a:note> 17 </a:notify> 18 </soap-env:Body> 19 </soap-env:Envelope>

The above SOAP message is a request for alert to a Web service. The request contains a text note (in the Body) and is marked (in the Header) to indicate that the message is high priority, but will become obsolete after the given time. The details are as follows: Lines 12: Prefix soap-env, declared in Line 2, identifies SOAP-defined elements, namely Envelope, Header, and Body, as well as the attribute mustUnderstand (appears in Line 7). Line 3: Prefix xsd refers to XML Schema elements, in particular the built-in type string (appears in Line 14). Line 4: Prefix xsi refers to XML Schema instance type attribute, asserting the type of the note as an XML Schema string (appears in Line 14). Line 7: The mustUnderstand attribute value "1" tells the Web service provider that it must understand the semantics of the header block and that it must process the header. The Web service requestor demands express service delivery. Lines 1218: The Body element encapsulates the service method invocation information, namely the method name notify, the method parameter note, its associated data type and its value. SOAP message body blocks carry the information needed for the end recipient of a message. The recipient must understand the semantics of all body blocks and must process them all. SOAP does not define the schema for body blocks since they are application specific. There is only one SOAP-defined body blockthe Fault element shown in Figure 8-4which is described below. A SOAP message can pass through multiple nodes on its path. This includes the initial SOAP sender, zero or more SOAP intermediaries, and an ultimate SOAP receiver. SOAP intermediaries are applications that can process parts Service Requestor Service Provider of a SOAP message as it travels from Receiver Sender Intermediary Intermediary the sender to the receiver. Intermediaries can both accept and forward (or relay, or route) SOAP messages. Three key usecases define the need for SOAP intermediaries: crossing trust domains, ensuring scalability, and providing value-added services along the SOAP message path. Crossing trust domains is a common issue faced when implementing security in distributed systems. Corporate firewalls and virtual private network (VPN) gateways let some requests cross the trust domain boundary and deny access to others. Similarly, ensuring scalability is an important requirement in distributed systems. We rarely have a simplistic scenario where the sender and receiver are directly connected by a dedicated link. In reality, there will be several network nodes on the communication path that will be crossed by many other concurrent communication flows. Due to the limited computing resources, the performance of these nodes may not scale well with the increasing traffic load. To ensure scalability, the intermediate nodes need to provide flexible buffering of messages and routing

Ivan Marsic

Rutgers University

300

based not only on message parameters, such as origin, destination, and priority, but also on the state of the network measured by parameters such as the availability and load of its nodes as well as network traffic information. Lastly, we need intermediaries to provide value-added services in a distributed system. Example services include authentication and authorization, security encryption, transaction management, message tracing and auditing, as well as billing and payment processing.

SOAP Message Global Attributes

SOAP defines three global attributes that are intended to be usable via qualified attribute names on any complex type referencing them. The attributes are as follows (more details on each are provided below): The mustUnderstand attribute specifies whether it is mandatory or optional that a message receiver understands and processes the content of a SOAP header block. The message receiver to which this attribute refers to is named by the role attribute. The role attribute is exclusively related to header blocks. It names the application that should process the given header block. The encodingStyle attribute indicates the encoding rules used to serialize parts of a SOAP message. Although the SOAP specification allows this attribute to appear on any element of the message (including header blocks), it mostly applies to body blocks. The relay attribute is used to indicate whether a SOAP header block targeted at a SOAP receiver must be relayed if not processed.

The mustUnderstand attribute can have values '1' or '0' (or, 'true' or 'false'). Value '1' indicates that the target role of this SOAP message must understand the semantics of the header block and process it. If this attribute is missing, this is equivalent to having value '0'. This value indicates that the target role may, but does not have to, process the header block. The role attribute carries an URI value that names the recipient of a header block. This can be the ultimate receiver or an intermediary node that should provide a value-added service to this message. The SOAP specification defines three roles: none, next, and ultimateReceiver. An attribute value of http://www.w3.org/2003/05/soap-envelope/role/next identifies the next SOAP application on the message path as the role for the header block. A header without a role attribute is intended for the ultimate recipient of this message. The encodingStyle attribute declares the mapping from an application-specific data representation to the wire format. An encoding generally defines a data type and data mapping between two parties that have different data representation. The decoding converts the wire representation of the data back to the application-specific data format. The translation step from one data representation to another, and back to the original format, is called serialization and deserialization. The terms marshalling and unmarshalling may be used as alternatives. The scope of the encodingStyle attribute is that of its owner element and that elements descendants, excluding the scope of the encodingStyle attribute on a nested element. More about SOAP encoding is given in Section 8.2.2 below.

Chapter 8

Web Services

301

The relay attribute indicates whether a header block should be relayed in the forwarded message if the header block is targeted at a role played by the SOAP intermediary, but not otherwise processed by the intermediary. This attribute type is Boolean and, if omitted, it is equivalent as if included with a value of false.

Error Handling in SOAP: The Fault Body Block

If a network node encounters problems while processing a SOAP message, it generates a fault message and sends it back to the message sender, i.e., in the direction opposite to the original message flow. The fault message contains a Fault element which identifies the source and cause of the error and allows error-diagnostic information to be exchanged between participants in an interaction. Fault is optional and can appear at most once within the Body element. The fault message originator can be an end host or an intermediary network node which was supposed to relay the original message. The content of the Fault element is slightly different in these two cases, as will be seen below. A Fault element consists of the following nested elements (shown in Figure 8-4): The Code element specifies the failure type. Fault codes are identified via namespacequalified names. SOAP predefines several generic fault codes and allows custom-defined fault codes, as described below. The Reason element carries a human-readable explanation of the message-processing failure. It is a plain text of type string along with the attribute specifying the language the text is written in. The Node element names the SOAP node (end host or intermediary) on the SOAP message path that caused the fault to happen. This node is the originator of the fault message. The Role element identifies the role the originating node was operating in at the point the fault occurred. Similar to the role attribute (described above), but instead of identifying the role of the recipient of a header block, it gives the role of the fault originator. The Detail element carries application-specific error information related to the Body element and its sub-elements.

As mentioned, SOAP predefines several generic fault codes. They must be namespace qualified and appear in a Code element. These are: Fault Code VersionMismatch Explanation The SOAP node received a message whose version is not supported, which is determined by the Envelope namespace. For example, the node supports SOAP version 1.2, but the namespace qualification of the SOAP message Envelope element is not identical to http://www.w3.org/2003/05/soap-envelope .

DataEncodingUnknown A SOAP node to which a SOAP header block or SOAP body child element information item was targeted was targeted does not support the data encoding indicated by the encodingStyle attribute. MustUnderstand A SOAP node to which a header block was targeted could not

Ivan Marsic

Rutgers University

302

process the header block, and the block mustUnderstand attribute value "true". Sender

contained

A SOAP message was not appropriately formed or did not contain all required information. For example, the message could lack the proper authentication or payment information. Resending this identical message will again cause a failure. A SOAP message could not be processed due to reasons not related to the message format or content. For example, processing could include communicating with an upstream SOAP node, which did not respond. Resending this identical message might succeed at some later point in time.

Receiver

SOAP allows custom extensions of fault codes through dot separators so that the right side of a dot separator refines the more general information given on the left side. For example, the Code element conveying a sender authentication error would contain Sender.Authentication. SOAP does not require any further structure within the content placed in header or body blocks. Nonetheless, there are two aspects that influence how the header and body of a SOAP message are constructed: communication style and encoding rules. These are described next.

8.2.2

The SOAP Section 5 Encoding Rules

Encoding rules define how a particular entity or data structure is represented in XML. Connecting different applications typically introduces the problem of interoperability: the data representation of one application is different from that of the other application. The reader may recall the example in Figure 6-1 that shows two different ways of representing a postal address. The applications may even be written in different programming languages. In order for the client and server to interoperate, it is essential that they agree on how the contents of a SOAP message are encoded. SOAP 1.2 defines a particular form of encoding called SOAP encoding.2 This defines how data structures in the applications local memory, including basic types such as integers and strings as well as complex types such as arrays and structures, can be serialized into XML. The serialized representation allows transfer of data represented in application-specific data types from one application to another. The encoding rules employed in a particular SOAP message are specified by the encodingStyle attribute, as discussed above. There is no notion of default encoding in a SOAP message. Encoding style must be explicitly specified if the receiving application is expected to validate the message. SOAP does not enforce any special form of codingother encodings may be used as well. In other words, applications are free to ignore SOAP encoding and choose a different one instead. For instance, two applications can simply agree upon an XML Schema representation of a data structure as the serialization format for that data structure. This is commonly referred to as literal encoding (see also Section 8.2.3 below).
2

There is no official name for SOAP encoding, but it is often referred to as SOAP Section 5 encoding, because the rules are presented in Section 5 of the SOAP specification.

Chapter 8

Web Services

303

A typical programming language data model consists of simple types and compound types. Compound types are based on simple types or other compound types. Dealing with simple data types would be easy, since all these types have direct representation in XML Schema (some are shown in Table 6-1 above). However, the story with complex types, such as arrays and arbitrary software objects, is more complicated. XML Schema defines complex types, but these are very general, and some degree of specialization, e.g., for arrays, could make job easier for the Web services developer. SOAP does not define an independent data type system. Rather, it relies on the XML Schema type system. It adopts all XML Schema built-in primitive types and adds few extensions for compound types. The SOAP version 1.2 types extending the XML Schema types are defined in a separate namespace, namely http://www.w3.org/2003/05/soap-encoding. XML elements representing encoded values may hold the XML Schema type attribute for asserting the type of a value. For example, the sender of the SOAP encoded message in Listing 8-1 above in Line 14 explicitly asserts the type of the note element content to be a string: 14 <a:note xsi:type="xsd:string"> 15 Reminder: meeting at 11AM in Rm.601 16 </a:note> The XML elements representing encoded values may also be untyped, i.e., not contain the type attribute: <a:note> Reminder: meeting at 11AM in Rm.601 </a:note> In this case, a receiver deserializing a value must be able to determine its type just by means of the element name <a:note>. If a sender and a receiver share the same data model, and both know that a note labeled value in an application-specific data graph is a string type, they are able to map the note element content to the appropriate data type without explicitly asserting the type through the XML Schema type attribute. However, in this case we cannot rely on XML Schema to explicitly validate the content of the message.

SOAP Compound Data Types

SOAP Section 5 encoding assumes that any application-specific data is represented as a directed graph. Consider the class diagram for an online auction site shown in Figure 2-27, Problem 2.16 in Chapter 2, which is simplified here in Figure 8-5. Suppose that the sender sends an instance of ItemInfo called item to the receiver in a SOAP message. A compound data type can be either a struct or an array. A struct is an element that contains different child elements. The SellerInfo in Figure 8-5 is an example of a struct. An array is a compound type that contains elements of the same name. The BidList in Figure 8-5 is an example of an array since it contains a group of individual Bid entries. When serialized to XML, the object graph of item in Figure 8-5 will be represented as follows: Listing 8-2: Example of SOAP encoding for the object graph in Figure 8-5.
<soap-env:Envelope xmlns:soap-env="http://www.w3.org/2003/05/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

Ivan Marsic

Rutgers University

304

item

ItemInfo name : String startPrice : float reserved : boolean bids BidsList 1 BuyerInfo seller 1 SellerInfo name : String address : String entry name : String address : String

*
Bid amount : float bidder 1

Sender
item SOAP message

Receiver (Web service)

Figure 8-5: Example class diagram, extracted from Figure 2-21 above.
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap-enc="http://www.w3.org/2003/05/soap-encoding" xmlns:ns0="http://www.auctions.org/ns" soap-env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"> <soap-env:Body> <ns0:item> <ns0:name xsi:type="xsd:string"> old watch </ns0:name> <ns0:startPrice xsi:type="xsd:float"> 34.99 </ns0:startPrice> <ns0:reserved xsi:type="xsd:boolean"> false </ns0:reserved> <ns0:seller> <ns0:name xsi:type="xsd:string"> John Doe </ns0:name> <ns0:address xsi:type="xsd:string"> 13 Takeoff Lane, Talkeetna, AK 99676 </ns0:address> <ns0:bids xsi:type="soap-enc:array" soap-enc:arraySize="*"> <ns0:entry> <ns0:amount xsi:type="xsd:float"> 35.01 </ns0:amount> <ns0:bidder> . . . </ns0:bidder> </ns0:entry> <ns0:entry> <ns0:amount xsi:type="xsd:float"> 34.50 </ns0:amount> <ns0:bidder> . . . </ns0:bidder> </ns0:entry> . . . </ns0:bids> </ns0:seller> </ns0:item> </soap-env:Body> </soap-env:Envelope>

Chapter 8

Web Services

305

<Envelope> <Header> header blocks </Header> <Body>

SOAP Message
arbitrary XML document (same for Request or Response) </Body> </Envelope>

Figure 8-6: Structure of a document-style SOAP message. Array attributes. Needed to give the type and dimensions of an arrays contents, and the offset for partially-transmitted arrays. Used as the type of the arraySize attribute. Restricts asterisk ( * ) to first list item only. Instances must contain at least an asterisk ( * ) or a nonNegativeInteger. May contain other nonNegativeIntegers as subsequent list items. Valid instances include: *, 1, * 2, 2 2, * 2 0.

8.2.3

SOAP Communication Styles

Generally, SOAP applications can communicate in two styles: document style and RPC style (Remote Procedure Call style). In document-style communication, the two applications agree upon the structure of documents exchanged between them. SOAP messages are used to transport these documents from one application to the other. The structure of both request and response messages is the same, as illustrated in Figure 8-6, and there are absolutely no restrictions as to the information that can be stored in their bodies. In short, any XML document can be included in the SOAP message. The document style is often referred to also as message-oriented style. In RPC-style communication, one SOAP message encapsulates the request while another message encapsulates the response, just as in document-style communication. However, the difference is in the way these messages are constructed. As shown in Figure 8-7, the body of the request message contains the actual operation call. This includes the name of the operation being invoked and its input parameters. Thus, the two communicating applications have to agree upon the RPC operation signature as opposed to the document structure (in the case of document-style communication). The task of translating the operation signature in SOAP is typically hidden by the SOAP middleware. Selecting the communication style is independent from selecting whether or not the message should be encoded (Section 8.2.2 above). The term literal is commonly used to refer to nonencoded messages. Therefore, four different combinations are possible: document/literal: A document-style message which is not encoded. document/encoded: A document-style message which is encoded. rpc/literal: An RPC-style message which is not encoded. rpc/encoded: An RPC-style message which is encoded.

Ivan Marsic

Rutgers University

306

Remote Procedure Call

(Request message)

<Envelope> <Header> header blocks </Header> <Body> <operationName> <inputParameter_1> <inputParameter_2> <inputParameter_n> </operationName> </Body> </Envelope>

value 1 value 2 value n

</inputParameter_1> </inputParameter_2> </inputParameter_n>

<Envelope> <Header> header blocks </Header> <Body> <operationNameReturn> <return> return value <outputParameter_1> value 1 <outputParameter_2> value 2 <outputParameter_n> </operationNameReturn> </Body> </Envelope> value n

</return> </outputParameter_1> </outputParameter_2> </outputParameter_n>

Remote Procedure Call Response

(Response message)

Figure 8-7: Structure of a SOAP RPC-style request and its associated response message. The document/encoded combination is rarely encountered in practice, but the other three are commonly in use. Document-style messages are particularly useful to support cases in which RPCs result in interfaces that are too fine grained and, therefore, brittle.

The RPC-style SOAP Communication

In the language of the SOAP encoding, the actual RPC invocation is modeled as a struct type (Section 8.2.2 above). The name of the struct (that is, the name of the first element inside the SOAP body) is identical to the name of the method/operation. Every in or in-out parameter of the RPC is modeled as an accessor with a name identical to the name of the RPC parameter and the type identical to the type of the RPC parameter mapped to XML according to the rules of the active encoding style. The accessors appear in the same order as do the parameters in the operation signature. All parameters are passed by value. SOAP has no notion of passing values by reference, which is unlike most of the programming languages. For Web services, the notion of in-out and out parameters does not involve passing objects by reference and letting the target application modify their state. Instead, copies of the data are exchanged. It is the up to the service client code to create the perception that the actual state of the object that has been passed in to the client method has been modified.

Listing 8-3: An example of a SOAP 1.2 RPC-style request/response via HTTP:

<?xml version="1.0"?>

Chapter 8

Web Services

307

<description name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns="http://www.w3.org/ns/wsdl"> <types> <schema targetNamespace="http://example.com/stockquote.xsd" xmlns="http://www.w3.org/2001/XMLSchema"> <element name="TradePriceRequest"> <complexType> <all> <element name="tickerSymbol" type="string"/> </all> </complexType> </element> <element name="TradePrice"> <complexType> <all> <element name="price" type="float"/> </all> </complexType> </element> </schema> </types> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceRequest"/> </message> <message name="GetLastTradePriceOutput"> <part name="body" element="xsd1:TradePrice"/> </message> <portType name="StockQuotePortType"> <operation name="GetLastTradePrice"> <input message="tns:GetLastTradePriceInput"/> <output message="tns:GetLastTradePriceOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetLastTradePrice"> <soap:operation soapAction="http://example.com/GetLastTradePrice"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding>

Ivan Marsic

Rutgers University

308

HTTP Message SOAP Message

Physical (Communication Protocol) Message POST / alertcontrol HTTP 1.1 Content-Type: text/xml; charset="utf-8" Content-Length: 581 Out-of-message context (target URI) Host: www.example.org SOAPAction: notify ...... Connection: Keep-Alive Out-of-message context (SOAPAction)

SOAP body

Logical SOAP Message <soap-env:Envelope xmlns:soap-env="http://www.w3.org/2003/05/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap-env:Header> ...... </soap-env:Header> In-message context (header blocks) ......

SOAP Body <soap-env:Body> <a:notify xmlns:a="http://example.org/alert"> <a:note xsi:type="xsd:string"> Reminder: meeting today at 11AM in Rm.601 </a:note> </a:notify> </soap-env:Body>

Figure 8-8: SOAP message binding to the HTTP protocol for the SOAP message example from Listing 8-1 above.
<service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> <description>

8.2.4

Binding SOAP to a Transport Protocol

The key issue in deciding how to bind SOAP to a particular transport protocol is about determining how the requirements for a Web service (communication style, such as RPC vs. document, synchronous vs. asynchronous, etc.) map to the capabilities of the transport protocol. In particular, we need to determine how much of the overall contextual information needed to successfully execute the Web service needs to go in the SOAP message versus in the message of the transport protocol. Figure 8-8 illustrates this issue on an HTTP example. In HTTP, context information is passed via the target URI and the SOAPAction header. In the case of SOAP, context information is passed in the SOAP header. As a communication protocol, SOAP is stateless and one-way. Although it is possible to implement statefull SOAP interactions so that the Web service maintains a session, this is not the most common scenario.

Chapter 8

Web Services

309

When using HTTP for SOAP messages, the developer must decide which HTTP method (Appendix C) is appropriate to use in HTTP request messages that are exchanged between the service consumer and the Web service. Usually the choice is between GET and POST. In the context of the Web as a whole (not specific to Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in [Jacobs, 2004]. Their finding is that GET is more appropriate for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). Figure 8-8 shows the HTTP request using the POST method, which is most often used in the context of Web services.

I. Jacobs (Editor), URIs, addressability, and the use of HTTP GET and POST, World Wide Web Consortium, 21 March 2004. Available at: http://www.w3.org/2001/tag/doc/whenToUseGet

8.3 WSDL for Web Service Description

A Web service publishes the description of the service not the actual service code. The service customer uses the aspects of the service description to look or find a Web service. The service customer uses this description since it can exactly detail what is required by the client to bind to the Web service. Service description can be partitioned into: Parts used to describe individual Web services. Parts used to describe relationships between sets of Web services.

Our main focus will be on the first group, describing individual Web services. The second group which describes relationships between sets of Web services will be briefly reviewed in Section 8.3.5 below. The most important language for describing individual Web services currently is the Web Services Definition Language (WSDL). WSDL has a dual purpose of specifying: (a) the Web service interface (operation names and their signatures, used in the service invocation), and (b) the Web service implementation (network location and access mechanism for a particular instance of the Web service). The interface specifies what goes in and what comes out, regardless of where the service is located or what are its performance characteristics. This is why the Web service interface is usually referred to as the abstract part of the service specification. Conversely, the implementation specifies the services network location and its non-functional characteristics, such as performance, reliability, and security. This is why the Web service implementation is usually referred to as the concrete part of the service specification. This section describes how WSDL is used for describing the service interface and implementation. WSDL grammar (schema) is defined using XML Schema. The WSDL service description is an XML document conformant to the WSDL schema definition. WSDL provides the raw technical description of the services interface including what a service does, how it is accessed and where

Ivan Marsic

Rutgers University

310

WSDL description Service interface definition types Abstract part: interface operation1 operation2
What types of messages (names + data types) are communicated with the service?

How are the methods invoked on the service?

Service implementation definition binding Concrete part: operation1 operation2 service

How will the service be used on the network for a protocol? SOAP-specific details are here.

Where is the service located in the network? endpoint host(s)

Figure 8-9: The WSDL 2.0 building blocks. a service is located (Figure 8-9). Since the Web service can be located anywhere in the network, the minimum information needed to invoke a service method is: 1. What is the service interface, that is, what are its methods (operations), method signatures, and return values? 2. Where in the network (host address and port number) is the service located? 3. What communication protocol does the service understand?

8.3.1

The WSDL 2.0 Building Blocks

As seen Figure 8-9, WSDL 2.0 enables the developer to separate the description of a Web services abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. Different implementations of the same Web service can be made accessible using different communication protocols. (Recall also that SOAP supports binding to different transport protocols, Section 8.2.4 above.) The description of the endpoints functional capabilities is the abstract interface specification represented in WSDL by the interface element. An abstract interface can support any number of operations. An operation is defined by the set of messages that define its interface pattern. Recall that invoking an object method involves a request message passing a set of parameters (or arguments) as well as receiving a response message that carries the result returned by the method. (The reader should recall the discussion of the RPC-style SOAP communication in Section 8.2.3 above.) Also, some of the method parameters may be used to pass back the output results; these are known as in-out or out parameters. Since the operation is invoked over the network, we must

Chapter 8

Web Services

311

wsdl:DescriptionType wsdl:import

wsdl:include

wsdl:description wsdl:types

!
wsdl:interface

!
wsdl:binding

!
wsdl:service

targetNamespace

Figure 8-10: The XML schema for WSDL 2.0. Continued in Figure 8-12 and Figure 8-14. (WSDL version 2.0 schema definition available at: http://www.w3.org/ns/wsdl). specify how the forward message carries the input parameters, as well as how the feedback message carries the result and the output parameters, or error message in case of failure. For the abstract concepts of messages and operations, concrete counterparts are specified in the binding element. A binding mechanism represented in WSDL by a binding element is used to map the abstract definition of the Web service to a specific implementation using a particular messaging protocol, data encoding model and underlying communication protocol. When the binding is combined with an address where the implementation can be accessed, the abstract endpoint becomes the concrete endpoint that service customers can invoke. The WSDL 2.0 schema defines the following high-level or major elements in the language (Figure 8-10, using the notation introduced in Figure 6-5): description Every WSDL 2.0 document has a description element as its top-most element. This merely acts as a container for the rest of the WSDL document, and is used to declare namespaces that will be used throughout the document. types Defines the collection of message types that can be sent to the Web service or received from it. Each message type is defined by the message name and the data types used in the message. The abstract interface of a Web service defined as a set of abstract operations. Each child operation element defines a simple interaction between the client and the service. The interaction is defined by specifying the messages (defined in the types element) that can be sent or received in the course of a service method invocation. Contains details of how the elements in an abstract interface are converted into concrete representation in a particular combination of data formats and transmission protocols. Must supply such details for every operation and fault in the interface. Specifies which interface the service implements, and a list of endpoint locations where this service can be accessed.

interface

binding

service

Ivan Marsic

Rutgers University

312

wsdl:DocumentationType wsdl:documentation

##other:any

##other:anyAttribute

Figure 8-11: The XML schema for WSDL 2.0 documentation element. As Figure 8-10 shows, WSDL 2.0 also offers import or interface inheritance mechanisms that are described below. Briefly, an import statement brings in other namespaces into the current namespace. An include statement brings in other element declarations that are part of the same (current) namespace. In other words, the key difference is whether the imported components are from the same or different namespace. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 Core Language) clearly states a set of constraints about how the child elements of the description element should be ordered. The required ordering is just as visualized in Figure 8-10, although multiple elements of the same type can be clustered together.

Documenting a Web Service Description

A WSDL document is inherently only a partial description of a service. Although it captures the basic mechanics of interacting with the servicethe message types, transmission protocols, service location, etc.in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked. The documentation element (Figure 8-11) allows the WSDL author to include some humanreadable documentation inside a WSDL document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. The documentation element is optional and can appear as a sub-element of any WSDL element, not only at the beginning of a WSDL document, since all WSDL elements are derived from wsdl:ExtensibleDocumentedType, which is a complex type containing zero or more documentation elements. This fact is omitted, for simplicity, in the Schema diagrams in this section.

Import and Include for Reuse of WSDL 2.0 Descriptions

The include element (Figure 8-10) helps to modularize the Web service descriptions so that separation of various service definition components from the same target namespace are allowed to exist in other WSDL documents which can be used or shared across Web service descriptions. This allows us to assemble a WSDL namespace from several WSDL documents that define components for that namespace. Some elements will be defined in the given document (locally) and others will be defined in the documents that are included in it via the include element. The effect of the include element is cumulative so that if document A includes document B which

Chapter 8

Web Services

313

in turn includes document C, then the components defined by document A comprise all those defined in A, B, and C. In contrast, the import element does not define any components. Instead, the import element declares that the components defined in this document refer to components that belong to a different namespace. No file is being imported; just a namespace is imported from one schema to another. If a WSDL document contains definitions of components that refer to other namespaces, then those namespaces must be declared via an import element. The import element also has an optional location attribute that is a hint to the processor where the definitions of the imported namespace can be found. However, the processor may find the definitions by other means, for example, by using a catalog. After processing any include elements and locating the components that belong to any imported namespaces, the WSDL component model for a WSDL document will contain a set of components that belong to this documents namespace and any imported namespaces. These components will refer to each other, usually via QName references. A WSDL document is invalid if any component reference cannot be resolved, whether or not the referenced component belongs to the same or a different namespace. The topic of importing is a bit more complex since two types of import statements exist: XML Schema imports and WDSL imports. Their respective behaviors are not quite identical and the interested reader should consult WSDL 2.0 specifications for details.

8.3.2

Defining a Web Services Abstract Interface

Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange pattern that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the in-out pattern (described below) indicates that if the client sends a message in to the service, the service will either send a reply message back out to the client (in the normal case) or it will send a fault message back to the client (in the case of an error). Figure 8-12 shows the XML syntax summary of the interface element, simplified by omitting optional <documentation> elements. The interface element has two optional attributes: styleDefault and extends. The styleDefault attribute can be used to define a default value for the style attributes of all operation sub-elements under this interface. Interfaces are referred to by QName in other components such as bindings. The optional extends attribute allows an interface to extend or inherit from one or more other interfaces. In such cases, the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must not themselves extend that interface either directly or indirectly. Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 Core Language) then they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact

Ivan Marsic

Rutgers University

314

wsdl:InterfaceType

! !

wsdl:InterfaceOperationType

operation

input

wsdl:interface

fault

output

##other:any name

infault

outfault

? ?

extends ##other:any styleDefault name

? ? ?

pattern safe style

Figure 8-12: The XML schema for WSDL 2.0 interface element. that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendants.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. Finally, since faults can also be defined as children of the interface element (as described in the following sections), the same name-collision rules apply to those constructs. The interface operation element has a required name attribute, while pattern, safe, and style are optional attributes.

WSDL Message Exchange Patterns

Message exchange patterns (MEPs) define the sequence and cardinality of messages within an operation. Eight types of message patterns are defined in the WSDL 2.0 specifications, but this list is not meant to be exhaustive and more patterns can be defined for particular application needs. Depending on how the first message in the MEP is initiated, the eight MEPs may be grouped into two groups: in-bound MEPs, for which the service receives the first message in the exchange, and out-bound MEPs, for which the service sends out the first message in the exchange. A service may use out-bound MEPs to advertise to potential clients that some new data will be made available by the service at run time. WSDL message exchange patterns use fault generation rules to indicate the occurrence of faults. Message exchange may be terminated if fault generation happens, regardless of standard rule sets. The following standard rule set outlines the behavior of fault generation:

Chapter 8

Web Services

315

<input>

<input>

A one-way operation:

Client

Service

Client

Service

In-Only (no faults)

Robust In-Only (message triggers fault)

A notification operation:

Client
<output>

Service

Client
<output>

Service

Out-Only (no faults) <output>

Robust Out-Only (message triggers fault) <output>

A solicit-response operation:

Client
<input>

Service

Client
<input>opt

Service

Out-In (fault replaces message) <input>

Out-Optional-In (message triggers fault) <input>

A request-response operation:

Client
<output>

Service

Client

Service
<output>opt

In-Out (fault replaces message)

In-Optional-Out (message triggers fault)

Figure 8-13: WSDL Message Exchange Patterns (MEPs) with their fault propagation rules. Fault Replaces Messageany message after the first in the pattern may be replaced with a fault message, which must have identical direction and be delivered to the same target node as the message it replaces Message Triggers Faultany message, including the first in the pattern, may trigger a fault message, which must have opposite direction and be delivered to the originator of the triggering message No Faultsfaults must not be propagated

pattern="http://www.w3.org/ns/wsdl/in-out" This line specifies that this operation will use the in-out pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does not mean that other WSDL 2.0 processors will automatically recognize or understand this pattern. As with any other extension, it can only be used among processors that do recognize and understand it.)

8.3.3

Binding a Web Service Implementation

Several service providers may implement the same abstract interface.

Ivan Marsic

Rutgers University

316

wsdl:BindingType

wsdl:BindingOperationType

operation

input

wsdl:binding

fault

output

##other:any name type

infault

outfault

##other:any

interface ref

Figure 8-14: The XML schema for WSDL 2.0 binding element.
wsdl:ServiceType wsdl:EndpointType

+
wsdl:service

endpoint ##other:any name binding

##other:any name

?
interface address

Figure 8-15: The XML schema for WSDL 2.0 service element. Figure 8-14 Service Each endpoint must also reference a previously defined binding to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. Figure 8-15 port describes how a binding is deployed at a particular network endpoint

8.3.4

Using WSDL to Generate SOAP Binding

Developers can implement Web services logic within their applications by incorporating available Web services without having to build new applications from scratch. The mechanism that makes this possible is the Proxy design pattern, which is described in Section 5.2.2 above and already employed for distributed computing in Section 5.4. Proxy classes enable developers to reference remote Web services and use their functionality within a local application as if the data the services return was generated in the local memory space. Figure 8-16 illustrates how WSDL is used to generate WSDL Web service description from the Web-services interface class. Given the WSDL document, both client- and server side use it to

Chapter 8

Web Services

317

WSDL document of service provider

1 2
WSDL compiler (server side) WSDL generator

3
WSDL compiler (client side)

Service requestor
Application object (client) Stub

Service provider
Application object (Web service) Skeleton

SOAP-based middleware

SOAP-based middleware

Figure 8-16: From a Programming Interface to WSDL and back to the Program: Step : generate WSDL documents from interface classes or APIs. Step : generate server-side stub from the WSDL document. Step : generate client-side stub from the WSDL document. generate the stub and skeleton proxies, respectively. These proxies interact with the SOAP-based middleware. WSDL code generator tools (one of which is reviewed in Section 8.5 below) allow automatic generation of Web services, automatic generation of WSDL documents, and invocation of Web services.

8.3.5

Non-functional Descriptions and Beyond WSDL

WDSL only describes functional characteristics of a particular Web service how to invoke it. But this is only part of the picture and will be sufficient only for standalone Web services that will be used individually. In some cases, non-functional characteristics (such as performance, security, reliability) may be important, as well. In a general case, the service consumer needs to know: How to invoke the service? (supported by WSDL, described above)

What are the characteristics of the service? (not supported by WSDL) Is a service more secure than the others are? Does a particular provider guarantee a faster response or a more scalable and reliable/available service? If there is a fee for the service, how does billing and payment processing work?

Ivan Marsic

Rutgers University

318

Service Broker UDDI Registry

ist e r 2.

Service level agreements Composition Orchestration Presentation Policy

lish /R eg

Pu b

Service Provider

3. Bind/Use

Service Customer

Implementation description Interface description XML Schema

Figure 8-17: Web service description stack. In what order should related Web services and their operations be invoked? supported by WSDL) (not

How can services be composed to create a macro service (often referred to as service orchestration)?

The diagram in Figure 8-17 lists the different aspects of Web service description. WSDL focuses on describing individual Web services, and interface and implementation descriptions are the central elements of describing individual services. Policy and presentation are two concepts that are not in the scope of the core WSDL specification since more standardization work needs to be done here. When considering service relationships, or service interactions, programmatic approaches (composition) vs. configuration-oriented agreements (orchestration) have to be distinguished. Orchestration is a synonym for choreography. An emerging specification is the Business Process Execution Language for Web Services (BPEL4WS). Figure 8-17 lists also service and business level agreements, both not yet defined in detail. Some Web services are so simple that they do not need the complete description as shown in Figure 8-17. A service consumer invoking a standalone service is probably not interested in how the service is orchestrated with other services. Sometimes the consumer does not care about nonfunctional characteristics, such as performance or reliability. In addition, non-functional characteristics may be irrelevant if only one provider exists for a service.

8.4 UDDI for Service Discovery and Integration

The discovery agency level connection is a publish/find mechanism (Figure 8-1), either used at build-time or runtime. Universal Description, Discovery, and Integration (UDDI) is an

Individual service description

1.

Service relationships

Service Description

Service Business level agreements Description

ea d/S Fin rch

Chapter 8

Web Services

319

implementation of the discovery agency. The UDDI registry offers a common repository to which service providers publish service information, and which service requestors inquire to find service information. UDDI defines a structure for the registry, together with a publishing and inquiry Application Programming Interface (API) for accessing the registry. If a service repository is used at runtime, we refer to this mode as dynamic Web services.

8.5 Developing Web Services with Axis

As the brief review above illustrates, the technology behind Web services is quite complex. Luckily, most Web services developers will not have to deal with this infrastructure directly. There are a number of Web services development toolkits to assist with developing and using Web services. There are currently many tools that automate the process of generating WSDL and mapping it to programming languages (Figure 8-16). One of the most popular such tools is Axis. Apache Axis (Apache EXtensible Interaction System, online at: http://ws.apache.org/axis/) is essentially a SOAP enginea framework for constructing SOAP processors such as clients, servers, gateways, etc. The current version of Axis is written in Java, but a C++ implementation of the client side of Axis is being developed. Axis includes a server that plugs into servlet engines such as Apache Tomcat, extensive support for WSDL, and tools that generate Java classes from WSDL. Axis provides automatic serialization/deserialization of Java Beans, including customizable mapping of fields to XML elements/attributes, as well as automatic two-way conversions between Java Collections and SOAP Arrays. Axis also provides automatic WSDL generation from deployed services using Java2WSDL tool for building WSDL from Java classes. The generated WSDL document is used by client developers who can use WSDL2Java tool for building Java proxies and skeletons from WSDL documents. Axis also supports session-oriented services, via HTTP cookies or transport-independent SOAP headers. The basic steps for using Apache Axis follow the process described in Section 8.3.4 above (illustrated in Figure 8-16). The reader may also wish to compare it to the procedure for using Java RMI, described in Section 5.4.2 above. The goal is to establish the interconnections shown in Figure 8-2.

8.5.1

Server-side Development with Axis

At the server side (or the Web service side), the steps are as follows:

Ivan Marsic

Rutgers University

320

1. Define Java interface of the Web service (and a class that implements this interface) 2. Generate the WDSL document from the services Java interface (Java WSDL) 3. Generate the skeleton Java class (server-side proxy) from the WSDL document (WSDL Java) 4. Modify the skeleton proxy to interact with the Java class that implements the Java interface (both created in Step 1 above) Going back to the project for Web-based Stock Forecasters (Section 1.5.2), I will now show how to establish the interconnections shown in Figure 8-2, so that a client could remotely connect to the Web service and request a price forecast for stocks of interest. The details for each of the above steps for this particular example are as follows.

Step 1: Define the server object interface

There are three key Java classes (from the point of view of Web services) responsible for providing a stock price forecast and trading recommendation (Figure 8-18(b)): ForecastServer.java, its implementation (ForecastServerImpl.java) and ParamsBean.java, a simple container object used to transfer information to and from the Web service. The structure of other packages in Figure 8-18(a) is not important at this point, since all we care about is the Web service interface definition, which will be seen by entities that want to access this Web service. The Java interface ForecastServer.java is given as: Listing 8-4: Java interface of the forecasting Web service.
1 2 3 4 5 6 7 8 9 10 11 12 package stock_analyst.interact; import java.rmi.RemoteException; public interface ForecastServer { public void getPriceForecast( ParamsBean args ) throws RemoteException; public void getRecommendation( ParamsBean args ) throws RemoteException; }

Chapter 8

Web Services

321

(a)

stock_analyst collect interact Web interaction analyze Internet Pattern learning & recognition (e.g., neural network) Gathering stock information database

(b)

interact

Generated by Axis WSDL2Java

ForecastServer + getPriceForecast(args : ParamsBean) + getRecommendation(args : ParamsBean)

ws Web service proxies (stub/skeleton)

ForecastServerImpl

ParamsBean parameters_ : HashMap<String, Object> + addParam(String, Object) + getParam(String) : Object + getParams( ) : <String, Object>

Internet

# numOfTrials_ : long # maxNumOfTrials_ : long + getPriceForecast(args : ParamsBean) + getRecommendation(args : ParamsBean)

Figure 8-18: (a) UML package diagram for the example application. (b) Web-service related classes. The code description is as follows: Line 1: Java package where the interface class is located. Line 2: Exception RemoteException may be thrown by the Web service methods. Lines 78: Method getPriceForecast() takes one input argument, which is a Java Bean used to transport information to and from the Web service. The method return type is void, which implies that any result values will be returned in the args parameter. Lines 1011: Method getRecommendation() signature, defined similarly as for the method getPriceForecast().

Ivan Marsic

Rutgers University

322

discovery agency : UDDI, WSIL Delphi method facilitator : Service Requestor : FcastSoapBindingStub http : Transport http : Transport wsdl/interact.wsdl : WSDL create obtain

data tracking and machine learning : Backend

analyst : ForecastServerImpl : FcastSoapBindingImpl

2
publish

3
initialize find get price forecast getPriceForecast()

4
getPriceForecast() do forecast

Figure 8-19: The steps in Apache Axis for establishing the interconnections of a Web service, overlaid on Figure 8-2. (Note that the discovery agency/UDDI is not implemented.)

Step 2: Java2WSDL Generate a WSDL document from the given stock-forecasting Java interface
Now that we defined the Java interface for the stock-forecasting service, it is time to generate a WSDL (Web Service Definition Language) file, which will describe our web service in a standard XML format. For this, we will use an Apache Axis command line tool Java2WSDL. A detailed documentation on Java2WSDL, its usage and parameters can be found at the Axis website.
% java org.apache.axis.wsdl.Java2WSDL -o wsdl/interact.wsdl -l "http://localhost:8080/axis/services/interact" -n "urn:interact" -p "stock_analyst.interact" "urn:interact" stock_analyst.interact.ForecastServer

Java2WSDL tool will generate a standard WSDL file, which is an XML representation of a given interface (ForecastServer.java in our case). We tell the program the information that it needs to know as it builds the file, such as: Name and location of output WSDL file ( -o wsdl/interact.wsdl ) Location URL of the Web service ( -l http://localhost:8080/axis/services/interact ) Target namespace for the WSDL ( -n urn:interact ) Map Java package to namespace ( stock_analyst.interact urn:interact )

Chapter 8

Web Services

323

The fully qualified Java interface of the Web service itself ( stock_analyst.interact.ForecastServer )

Step 3: WSDL2Java Generate server-side wrapper code

(This step generates code for both server and client side, as seen below.) Our next step is to take the WSDL, synthesized in step 2, and generate all of the glue code for deploying the service. The WSDL2Java Axis tool comes to our aid here. Complete documentation on this tool can be found at the Axis website.
java org.apache.axis.wsdl.WSDL2Java -o src/ -d Session -s -p stock_analyst.interact.ws wsdl/interact.wsdl

Once again, we need to tell our tool some information for it to proceed: Base output directory ( -o src/ ) Scope of deployment ( Application, Request, or Session ) Turn on server-side generation ( -s ) we would not do this if we were accessing an external Web service, as we would then just need the client stub Package to place code ( -p stock_analyst.interact.ws ) Name of WSDL file used to generate all this code ( wsdl/interact.wsdl ) For separating the automatically generated code from the original code, we store it a new Web service package stock_analyst.interact.ws, shown in Figure 8-18(b). After running the WSDL2Java code generator, we get the following files under src/stock_analyst/interact/ws: FcastSoapBindingImpl.java This is the implementation code for our web service. We will need to edit it, to connect it to our existing ForecastServerImpl (see Step 4 below). ForecastServer.java This is a remote interface to the stock forecasting system (extends Remote, and methods from the original ForecastServer.java throw RemoteExceptions). ForecastServerService.java Service interface of the Web services. ForecastServerServiceLocator.java A helper factory for retrieving a handle to the service. FcastSoapBindingStub.java Client-side stub code that encapsulates client access.

Ivan Marsic

Rutgers University

324

ParamsBean.java A copy of our bean used to transfer data. deploy.wsdd Deployment descriptor that we pass to Axis system to deploy these Web services. undeploy.wsdd Deployment descriptor that will un-deploy the Web services from the Axis system.

As seen above, some of these files belong to the client side and will be used in Section 8.5.2 below.

Step 4: Tune-up Modify FcastSoapBindingImpl.java to call server implementation code

We need to tweak one of the output source files to tie the web service to our implementation code (ForecastServerImpl.java). Since we passed a mere interface to the Java2WSDL tool, the generated code has left out the implementation. We need to fill out the methods to delegate the work to our implementation object ForecastServerImpl. FcastSoapBindingImpl.java is waiting for us to add the stuff into the methods that it created. The lines that should be added are highlighted in boldface in Listing 8-5: Listing 8-5: FcastSoapBindingImpl.java Java code automatically generated by Axis, with the manually added modifications highlighted in boldface.
1 2 3 4 5 5a 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 package stock_analyst.interact.ws; import stock_analyst.interact.ForecastServerImpl; public class FcastSoapBindingImpl implements stock_analyst.interact.ForecastServer { ForecastServerImpl analyst; public FcastSoapBindingImpl() throws java.rmi.RemoteException { analyst = new ForecastServerImpl(); } public void getPriceForecast( stock_analyst.interact.ParamsBean inout0 ) throws java.rmi.RemoteException { return analyst.getPriceForecast( inout0 ); } public void getRecommendation( stock_analyst.interact.ParamsBean inout0 ) throws java.rmi.RemoteException { return analyst.getRecommendation( inout0 ); } }

Chapter 8

Web Services

325

Step 5: Compile and deploy

We first need to compile and compress our newly generated Web service, including both the original code and the automatically generated Web service code:
javac -d bin src/stock_analyst.interact.ws/*.java cd bin jar -cvf ../stock_analyst.jar * cd ..

Finally, we copy the JAR file into Tomcat library path visible by Axis and deploy it:
cp stock_analyst.jar $TOMCAT_HOME/webapps/axis/WEB-INF/lib/ --reply=yes java org.apache.axis.client.AdminClient -l "http://localhost:8080/axis/services/AdminService" src/stock_analyst/interact/ws/deploy.wsdd

Admin client is yet another command line tool provided by Apache Axis, which we can use to do tasks such as deployment, un-deployment, and listing the current deployments. We pass the deployment descriptor to this program so it can do its work. Now our Stock Forecasting Web Service is up and running on the server.

8.5.2

Client-side Development with Axis

At the client side (or the service consumer side), the steps are as follows: 1. Generate the stub Java class (server-side SOAP proxy) from the WSDL document 2. Modify the client code to invoke the stub (created in Step 1 above)

Step 1: WSDL2Java Generate client-side stub

The Step 1 is the same as Step 3 for the server side, except that this time we omit the option -s on the command line. We have seen above that WSDL2Java generated the client-side stub code FcastSoapBindingStub.java that encapsulates client access.

Step 2: Modify the client code to invoke the stub

Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. Recall that ForecastServerServiceLocator.java was generated in Step 3 of the server side. This locator is derived from the service element in the WSDL document. WSDL2Java generates two objects from each service element. The service interface defines a get method for each endpoint listed in the service element of the WSDL document. The locator is the implementation of this service interface. It implements these get methods. It serves as a locator for obtaining Stub instances. The Service class will

Ivan Marsic

Rutgers University

326

generate, by default, a Stub that points to the endpoint URL described in the WSDL document, but you may also specify a different URL when you ask for the endpoint. A typical usage of the stub classes would be as follows Listing 8-6: Listing 8-6: Example of the Delphi method facilitator client for the project Web-based Stock Forecasters (Section 1.5.2).
1 2 3 4 5 6 7 8 9 9a 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 package facilitator.client; import stock_analyst.interact.ws.ForecastServerService; import stock_analyst.interact.ws.ForecastServerServiceLocator; public class Facilitator { public static void main(String [] args) throws Exception { // Make a service ForecastServerService service1 = new ForecastServerServiceLocator(); // Now use the service to get a stub which implements the SDI. ForecastServer endpoint1 = service1.getForecastServer(); // Prepare the calling parameters ParamsBean args = new ParamsBean(); args.addParam("...", "..."); // 1st parameter ... etc. ... // 2nd parameter // Make the actual call try { endpoint1.getRecommendation(args); args.getParam("result", ...); // retrieve the recommendation // ... do something with it ... } catch (RemoteException ex) { // handle the exception here } ... call endpoint2 (i.e. another forecaster web service) } }

The above example shows how the facilitator would invoke a single Web service. As described in Section 1.5.2, the facilitator would try to consult several forecasters (Web services) for their prognosis and then integrate their answers into a single recommendation for the user.

8.6 OMG Reusable Asset Specification

http://www.rational.com/ras/index.jsp http://www.eweek.com/article2/0,4149,1356550,00.asp http://www.sdtimes.com/news/092/story4.htm

Chapter 8

Web Services

327

http://www.cutter.com/research/2002/edge020212.html http://www.computerworld.co.nz/news.nsf/0/B289F477F155A539CC256DDE00631AF8?OpenDocument

8.7 Summary and Bibliographical Notes

SOAP is an XML-based communication protocol and encoding format for inter-application communication. SOAP provides technology for distributed object communication. Given the signature of a remote method (Web service) and the rules for invoking the method, SOAP allows for representing the remote method call in XML. SOAP supports loose-coupling of distributed applications that interact by exchanging one-way asynchronous messages among each other. SOAP is not aware of the semantics of the messages being exchanged through it. Any communication pattern, including request-response, has to be implemented by the applications that use SOAP for communication. The body of the SOAP message can contain any arbitrary XML content as the message payload. SOAP is widely viewed as the backbone to a new generation of cross-platform cross-language distributed computing applications, termed Web services. Service description plays a key role in a service-oriented architecture (SOA) in maintaining the loose coupling between the service customers and the service providers. Service description is a formal mechanism to unambiguously describe a Web service for the service customers. A Service description is involved in each of the three operations of SOA: publish, find and bind. In this chapter I reviewed the WSDL version 2.0 standard for describing Web services and how it is used to provide functional description of the Web services SOA model. There are other standards such as Web Services Flow Language (WSDL) and WSEL (Web Services Endpoint Language) which are used to describe the non functional aspects of Web services. The reader interested in these should consult the relevant Web sources. WSDL 2.0 is the current standard at the time of this writing. It is somewhat different from the previous version WSDL 1.1, and the interested reader may wish to consult [Dhesiaseelan, 2004] for details. Although WSDL 1.1 is currently more widely supported in web service implementations, I chose to present WSDL 2.0 because it is simpler and more recent. Briefly, a reader familiar with WSDL 1.1 will notice that WSDL 2.0 does not have message elements. These are specified using the XML Schema type system in the types element. Also, portType element is renamed to interface and port is renamed to endpoint. Web Services Inspection Language (WSIL)is a lightweight alternative to UDDI. The W3C website and recommendation documents for SOAP are at: http://www.w3.org/TR/soap/. The latest is SOAP version 1.2 specification. This document has been produced by the XML Protocol Working Group, which is part of the Web Services Activity.

Ivan Marsic

Rutgers University

328

http://soapuser.com/ WSDL at: http://www.w3.org/TR/wsdl20

[Armstrong et al., 2005] A. Dhesiaseelan, Whats new in WSDL 2.0, published on XML.com, May 20, 2004. Available at: http://webservices.xml.com/lpt/a/ws/2004/05/19/wsdl2.html

Problems
Section 8.3
7.1 WSDL, although flexible, is rather complex and verbose. Suppose you will develop a set of Web services for a particular domain, e.g., travel arrangements. Define your own service language and then use XSLT to generate the WSDL.

7.2 Tbd

Future Trends

Chapter 9

Contents
Most people are drawn into extrapolating from current trends and are thus surprised when things change. Buttonwood (The Economist, January 3rd 2009)

9.1 Aspect-Oriented Programming

9.1.1 9.1.2 9.1.3 9.1.4 9.1.5 9.1.6 9.1.7 9.1.8

It is widely recognized that software engineering is not a mature discipline, unlike other branches of engineering. However, this does not imply that great feats cannot be accomplished with the current methods and techniques. For example, the art of building such elaborate structures as cathedrals was perfected during the so called dark ages, before the invention of calculus, which is a most basic tool of civil engineering. What the discipline of civil engineering enabled is the wide-scale, mass-market building of complex structures, with much smaller budgets and over much shorter time-spans. Hence, it is to be expected that successful software products can be developed with little or none application of software engineering principles and techniques. What one hopes is that the application of these principles will contribute to reduced costs and improved quality.

9.2 OMG MDA

9.2.1 9.2.2 9.2.3 9.2.4

9.3 Autonomic Computing

9.3.1 9.3.2 9.3.3 9.3.4 9.2.3

9.4 Software-as-a-Service (SaaS)

9.4.1 9.4.2 9.4.3 9.4.4

9.5 End User Software Development

9.5.1 9.5.2 9.5.3 9.5.4

Meta-programming is the term for the art of developing methods and programs to read, manipulate, and/or write other programs. When what is developed are programs that can deal with themselves, we talk about reflective programming. http://cliki.tunes.org/Metaprogramming http://fare.tunes.org/articles/ll99/index.en.html

9.6 The Business of Software

9.6.1 9.6.2 9.6.3

9.7 Summary and Bibliographical Notes

329

Ivan Marsic

Rutgers University

330

9.1 Aspect-Oriented Programming

[ See also Section 3.4. ] There has been recently recognition of limitations of the object-orientation idea. We are now seeing that many requirements do not decompose neatly into behavior centered on a single locus. Object technology has difficulty localizing concerns involving global constraints and pandemic behaviors, appropriately segregating concerns, and applying domain-specific knowledge. Postobject programming (POP) mechanisms, the space of programmatic mechanisms for expressing crosscutting concerns. Aspect-oriented programming (AOP) is a new evolution of the concept for the separation of concerns, or aspects, of a system. This approach is meant to provide more modular, cohesive, and well-defined interfaces or coupling in the design of a system. Central to AOP is the notion of concerns that cross cut, which means that the methods related to the concerns intersect. Dominant concerns for object activities, their primary function, but often we need to consider crosscutting concerns. For example, an employee is an accountant, or programmer, but also every employee needs to punch the timesheet daily, plus watch security of individual activities or overall building security, etc. It is believed that in OO programming these cross-cutting concerns are spread across the system. Aspect-oriented programming would modularize the implementation of these crosscutting concerns into a cohesive single unit.

The term for a means of meta-programming where a programming language is separated into a core language and various domain-specific languages which express (ideally) orthogonal aspects of program behavior. One of the main benefits of this means of expression is that the aspect programs for a given system are often applicable across a wide range of elements of the system, in a crosscutting manner. That is, the aspects pervasively effect the way that the system must be implemented while not addressing any of the core domain concerns of the application. One of the drawbacks to this approach, beyond those of basic meta-programming, is that the aspect domains are often only statically choosable per language. However, the benefits are that separate specification is possible, and that these systems combine to form valid programs in the original (non-core) programming language after weave-time, the part of compilation where the aspect programs are combined with the core language program. http://cliki.tunes.org/Aspect-Oriented%20Programming

http://www.eclipse.org/aspectj/ Crosscutting concerns: ...a system that clocks employees in and out of work. ...and businesses everywhere use machines to identify employees as they check in and out of work.

Chapter 9

Some Future Trends

331

9.2 OMG MDA

9.3 Autonomic Computing

Gilbs laws of computer unreliability: Computers are unreliable, but humans are even more unreliable. Self-checking systems tend to have an inherent lack of reliability of the system in which they are used. The error-detection and correction capabilities of any system will serve the key to understanding the type of error which they can not handle. Undetectable errors are infinite in variety, in contrast to detectable errors, which by definition are limited.

With the mass-market involvement of developers with a wide spectrum of skills and expertise in software development, one can expect that the quality of software products will widely vary. Most of the products will not be well engineered and reliable. Hence it becomes an imperative to develop techniques that can combine imperfect components to produce reliable products. Wellknown techniques from fault-tolerance can teach us a great deal in this endeavor. Unfortunately, our ability to build dependable systems is lagging significantly compared to our ability to build feature-rich and high-performance systems. Examples of significant system failures abound, ranging from the frequent failures of Internet services [cite Patterson and Gray Thu.] As we build ever more complex and interconnected computing systems, making them dependable will become a critical challenge that must be addressed.

IBM: Computer heal thyself http://www.cnn.com/2002/TECH/biztech/10/21/ibm.healing.reut/index.html GPS, see Marvin Minskys comments @EDGE website

You may also find useful the overview of GPS in AI and Natural Man by M. Boden, pp 354-356. http://www.j-paine.org/students/tutorials/gps/gps.html

The importance of abstract planning in real-world tasks. Since the real world does not stand still (so that one can find to ones surprise that the environment state is unfamiliar), it is not usually sensible to try to formulate a detailed plan beforehand. Rather, one should sketch the broad outlines of the plan at an abstract level and then wait and see what adjustments need to be made in execution. The execution-monitor program can pass real-world information to the planner at the time of carrying out the plan, and tactical details can be filled in accordingly. Some alternative possibilities can sensibly be allowed for in the high level plan (a case of contingency planning), but the notion that one should specifically foresee all possible contingencies is absurd. Use of a

Ivan Marsic

Rutgers University

332

hierarchy of abstraction spaces for planning can thus usefully mask the uncertainties inherent in real-world action.

The problem may not be so much in bugs with individual componentsthose are relatively confined and can be uncovered by methodical testing of each individually. A greater problem is when they each work independently but not as a combination, i.e., combination of rights yields wrong [see Boden: AI].

9.4 Software-as-a-Service (SaaS)

Offline access is a concern with many SaaS (Software as a Service) models. SaaS highlights the idea of the-network-as-a-computer, an idea a long time coming. Software as a Service (SaaS): http://en.wikipedia.org/wiki/Software_as_a_Service Software as a Service: A Major Challenge for the Software Engineering: http://www.service-oriented.com/ A field guide to software as a service | InfoWorld | Analysis: http://www.infoworld.com/article/05/04/18/16FEsasdirect_1.html IBM Software as Services: http://www-304.ibm.com/jct09002c/isv/marketing/saas/ Myths and Realities of Software-as-a-Service (SaaS): http://www.bitpipe.com/tlist/Software-as-aService.html

9.5 End User Software Development

The impetus for the current hype: Web 2.0, that second-generation wave of Net services that let people create content and exchange information online. For an eloquent discussion of the concept of end user computing see: James Martin, Application Development Without Programmers, Prentice Hall, Englewood Cliffs, NJ, 1982. [ QA76.6.M3613 ]

Researchers seek simpler software debugging/programming http://www.cnn.com/2004/TECH/ptech/07/27/debugging.ap/index.html Whyline -- short for Workspace for Helping You Link Instructions to Numbers and Events // Brad Myers, a Carnegie Mellon University computer science professor

Chapter 9

Some Future Trends

333

[Kelleher & Pausch, 2005] Lieberman, Henry; Patern, Fabio; Wulf, Volker (Editors), End-User Development, Springer Series: Human-Computer Interaction Series, Vol. 9, 2005, Approx. 495 p., Hardcover, ISBN: 14020-4220-5 (2006. 2nd printing edition) Henry Lieberman, Your Wish Is My Command: Programming by Example, (Interactive Technologies), Morgan Kaufmann; 1st edition (February 27, 2001) Allen Cypher (Editor), Watch What I Do: Programming by Demonstration, The MIT Press (May 4, 1993) [Maeda, 2004]

Is it possible to bring the benefits of rigorous software engineering methodologies to end-users? Project called End Users Shaping Effective Software, or EUSES -- to make computers friendlier for everyday users by changing everything from how they look to how they act. Margaret Burnett, a computer science professor at Oregon State University and director of EUSES. http://eecs.oregonstate.edu/EUSES/

See discussion of levels of abstraction in the book Wicked Problems; notice that the assembly programming is still alive and well for low-end mobile phone developers.

Making Good Use of Wikis Sure, it sounds like a child's toy. But a special type of wiki, from JotSpot, can actually take the place of a database application. I spent some time with it recently, and it felt like seeing the first version of dBase all over again. It's rough--but you can create some nifty little applications with e-mail integration pretty quickly. Check out http://www.pcmag.com/article2/0,1759,1743602,00.asp our story about JotSpot, and see if maybe it'll help you overcome your systems backlog. See also: Business Week, October 18, 2004, pages 120-121: Hate Your Software? Write Your Own http://www.businessweek.com/magazine/content/04_42/b3904104_mz063.htm Tools to ease Web collaboration: JotSpot competing against Socialtext and a handful of others like Five Across and iUpload in the fledgling market http://www.cnn.com/2005/TECH/internet/02/16/web.collaboration.ap/index.html

Wikis, one of the latest fads in making programming accessible to the masses is a programming equivalent of Home Depotfix it yourself tools. Sure, it was about time to have a Home Depot

Ivan Marsic

Rutgers University

334

of software. However, I am not aware that the arrival of Home Depot spelled the end of the civil engineering profession, as some commentators see it for professional software developers. As with Home Depot, it works only for little things; after all, how many of us dare to replace kitchen cabinets, lest to mention building a skyscraper!

Web services BPEL and programming workflows on a click

4GL and the demise of programming: What happened to CASE and 4GL? My suspicion is that we still use them to this day, but the terms themselves have fallen into such disregard that we rarely see them. And certainly, the hyped benefits were never achieved.

The Future of Programming on the iSeries, Part 2 by Alex Woodie and Timothy Prickett Morgan http://www.itjungle.com/tfh/tfh042803-story01.html

Why assembler? by A. F. Kornelis http://www.bixoft.nl/english/why.htm

The Future of the Programmer; InformationWeek's Dec. 6 issue http://blog.informationweek.com/001855.html

Application Development Trends Articles (5/2/2006): End-user programming in five minutes or less ---- By John K. Waters Rod Smith, IBM's VP of Internet emerging technologies, chuckles at the phrase "end-user programming," a term he says has been overhyped and overpromised. And yet, IBM's new PHPbased QEDWiki project ("quick and easily done wiki") is focused on that very concept. QEDWiki is an IDE and framework designed to allow non-technical end users to develop socalled situational apps in less than five minutes. http://www.adtmag.com/article.aspx?id=18460 Web 2.0: The New Guy at Work -- Do-it-yourself trend http://www.businessweek.com/premium/content/06_25/b3989072.htm ONLINE EXTRA: How to Harness the Power of Web 2.0 http://www.businessweek.com/premium/content/06_25/b3989074.htm

Chapter 9

Some Future Trends

335

9.6 The Business of Software

Those who want information to be free as a matter of principle should create some information and make it free. Nicholas Petreley Linux is only free if your time is worthless. Jeremy F. Hummond

Traditionally, software companies mostly made profits by product sales and license fees. Recently, there is a dramatic shift to services, such as annual maintenance payments that entitle users to patches, minor upgrades, and often technical support. This shift has been especially pronounced among enterprise-software vendors. There are some exceptions. Product sales continue to account for most of game-software revenues, although online-gaming service revenues are growing fast. Also, the revenues of platform companies such as Microsoft are still dominated by product revenues. A possible explanation for that the observed changes is that this is simply result of life-cycle dynamics, which is to say that the industry is in between platform transitions such as from desktop to the Web platform, or from office-bound to mobile platforms. It may be also that a temporary plateau is reached and the industry is awaiting a major innovation to boost the product revenue growth. If a major innovation occurs, the individuals and enterprises will start again buying new products, both hardware and software, in large numbers. Another explanation is that the shift is part of a long-term trend and it is permanent for the foreseeable future. The argument for this option is that much software now is commoditized, just like hardware, and prices will fall to zero or near zero for any kind of standardized product. In this scenario, the future is really free software, inexpensive software-as-a-service (SaaS), or free, but not free software, with some kind of indirect pricing model, like advertisinga Google-type of model. An interested reader should see [Cusumano, 2008] for a detailed study of trends in software business. [Watson, et al., 2008] about the business of open source software The advantages of open source software include a free product and community support. However, there are disadvantages as well. Communities do not usually respond as quickly to help requests, and they do not offer inexperienced users one-on-one instruction.

9.7 Summary and Bibliographical Notes

Java Programming

Appendix A

This appendix offers a very brief introduction to Java programming; I hope that most of my readers will not need this refresher. References to literature to find more details are given at the end of this appendix.

A.1 Introduction to Java Programming

This review is designed to give the beginner the basics quickly. The reader interested in better understanding of Java programming should consult the following sources.

Bibliographical Notes
This is intended as a very brief introduction to Java and the interested reader should consult many excellent sources on Java. For example, [Eckel, 2003] is available online at http://www.mindview.net/Books. Another great source is [Sun Microsystems, 2005], online at http://java.sun.com/docs/books/tutorial/index.html. More useful information on Java programming is available at http://www.developer.com/ (Gamelan) and http://www.javaworld.com/ (JavaWorld magazine).

336

Network Programming

Appendix B

In network programming, we establish a connection between two programs, which may be running on two different machines. The client/server model simplifies the development of network software by dividing the design process into client issues and server issues. We can draw a telephone connection analogy, where a network connection is analogous to a case of two persons talking to each other. A caller can dial a callee only if it knows the callees phone number. This should be advertised somewhere, say in a local telephone directory. Once the caller dials the well-known number it can start talking if the callee is listening on this number. In the client/server terminology, the program which listens for the incoming connections is called a server and the program which attempts the dialing a well-known phone number is called a client. A server is a process that is waiting to be contacted by a client process so that it can do something for the client.

B.1 Socket APIs

Network programming is done by invoking socket APIs (Application Programming Interfaces). These socket API syntax is common across operating systems, although there are slight but important variations. The key abstraction of the socket interface is the socket, which can be thought of as a point where a local application process attaches to the network. The socket interface defines operations for creating a socket, attaching the socket to the network, sending/receiving messages through the socket, and closing the socket. Sockets are mainly used over the transport layer protocols, such as TCP and UDP; this overview is limited to TCP. A socket is defined by a pair of parameters: the host machines IP address and the applications port number. A port number distinguishes the programs running on the same host. It is like an extension number for persons sharing the same phone number. Internet addresses for the Internet Protocol version 4 (IPv4) are four-byte (32 bits) unsigned numbers. They are usually written as dotted quad strings, for example, 128.6.68.10, which corresponds to the binary representation 10000000 00000110 01000100 00001010. The port numbers are 16-bit unsigned integers, which can take values in the range 0 65535. Port numbers 0 1024 are reserved and can be assigned to a process only by a superuser process. For example, port number 21 is reserved for the FTP server and port number 80 is reserved for the Web server. Thus, a pair

337

Ivan Marsic

Rutgers University

338

(128.6.68.10, 80) defines the socket of a Web server application running on the host machine with the given IP address. Alphanumeric names are usually assigned to machines to make IP addresses human-friendly. These names are of variable length (potentially rather long) and may not follow a strict format. For example, the above IP address quad 128.6.68.10 corresponds to the host name eden.rutgers.edu. The Domain Name System (DNS) is an abstract framework for assigning names to Internet hosts. DNS is implemented via name servers, which are special Internet hosts dedicated for performing name-to-address mappings. When a client desires to resolve a host name, it sends a query to a name server which, if the name is valid, and returns back the hosts IP address1. Here, I will use only the dotted decimal addresses. In Java we can deal directly with string host names, whereas in C we must perform name resolution by calling the function gethostbyname(). In C, even a dotted quad string must be explicitly converted to the 32-bit binary IP address. The relevant data structures are defined in the header file netinet/in.h as follows: C socket address structures (defined in netinet/in.h)
struct in_addr { unsigned long s_addr; }; struct sockaddr_in { sa_family_t in_port_t struct in_addr char }; /* Internet address (32 bits) */

sin_family; sin_port; sin_addr; sin_zero[8];

/* /* /* /*

Internet protocol (AF_INET) */ Address port (16 bits) */ Internet address (32 bits) */ Not used */

To convert a dotted decimal string to the binary value, we use the function inet_addr():
struct sockaddr_in host_addr; host_addr.sin_addr.s_addr = inet_addr("128.6.68.10");

The name resolution process is rather complex, because the contacted name server may not have the given host name in its table, and the interested reader should consult a computer networking book for further details.

Appendix B

Network Programming

339

Client
ServerSocket rv_sock = new ServerSocket(port); Socket s_sock = rv_sock.accept();

Server
Step 1: Run the server

Step 2: Run the client

Socket c_sock = new Socket(host_name, port);

Server blocked

Time

Step 3: Send a request message

BufferedReader in = new BufferedReader( new InputStreamReader( c_sock.getInputStream() )); PrintWriter out = new PrintWriter( new OutputStreamWriter( c_sock.getOutputStream() )); String rqst_msg = ... ; out.println(rqst_msg);

BufferedReader in = new BufferedReader( new InputStreamReader( s_sock.getInputStream() )); PrintWriter out = new PrintWriter( new OutputStreamWriter( s_sock.getOutputStream() ));

Step 4:

String rqst_msg = in.readLine(); Receive request

String rslt_msg = ... ; out.println(rslt_msg);

Step 5: Do processing Step 6: Send the result message

Step 7: Receive result

String rslt_msg = in.readLine();

c_sock.close();

s_sock.close();

Figure B-1: Summary of network programming in the Java programming language. Figure B-1 summarizes the socket functions in Java for a basic client-server application. Similarly, Figure B-2 summarizes the socket functions in C. Although this figure may appear simpler than that for Java, this is deceptive because the Java constructs incorporate much more than necessary for this simple example. The first step is to create a socket, for which in C there is only one function: socket(). Java distinguishes two types of sockets that are implemented over the TCP protocol: server sockets from client sockets. The former are represented by the class java.net.ServerSocket and the latter by the class java.net.Socket. In addition, there is java.net.DatagramSocket for sockets implemented over the UDP protocol. The following example summarizes the Java and C actions for opening a (TCP-based) server socket: Opening a TCP SERVER socket in Java vs. C (Passive Open)
import java.net.ServerSocket; import java.net.Socket; public static final int PORT_NUM = 4999; ServerSocket rv_sock = new ServerSocket(PORT_NUM); #include <arpa/inet.h> #include <sys/socket.h> #define PORT_NUM 4999 int rv_sock, s_sock, cli_addr_len; struct sockaddr_in serv_addr, cli_addr; rv_sock = socket( PF_INET, SOCK_STREAM, IPPROTO_TCP); serv_addr.sin_family = AF_INET; serv_addr.sin_addr.s_addr = htonl(INADDR_ANY); serv_addr.sin_port = htons(PORT_NUM); bind(rv_sock,

Ivan Marsic

Rutgers University

340

Client

Server
int rv_sock = socket( domain, type, protocol); bind(rv_sock, addr, addr_len); listen(rv_sock, bcklog); int s_sock = accept( rv_sock, addr, addr_len);

Step 1: Run the server

Step 2: Run the client

int c_sock = socket( domain, type, protocol); connect(c_sock, addr, addr_len); char *rqst_msg = ...; send(c_sock, rqst_msg, msg_len, flags);

Time

Server blocked
char *buffer = malloc(buf_len); recv(s_sock, buffer, buf_len, flags);

Step 3: Send a request message

Step 4: Receive request Step 5: Do processing Step 6: Send the result message

char *rslt_msg = ...; send(s_sock, rslt_msg, msg_len, flags);

Step 7: Receive result

char *buffer = malloc(buf_len); recv(c_sock, buffer, buf_len, flags); close(c_sock); close(s_sock);

Figure B-2: Summary of network programming in the C programming language.

&serv_addr, sizeof(serv_addr)); listen(rv_sock, 5); cli_addr_len = sizeof(cli_addr); s_sock = accept(rv_sock, &cli_addr, &cli_addr_len);

Socket s_sock = rv_sock.accept();

The above code is simplified, as will be seen in the example below, but it conveys the key points. Notice that in both languages we deal with two different socket descriptors. One is the so-called well-known or rendezvous socket, denoted by the variable rv_sock. This is where the server listens, blocked and inactive in the operation accept(), waiting for clients to connect. The other socket, s_sock, will be described later. In Java, you simply instantiate a new ServerSocket object and call the method accept() on it. There are several different constructors for ServerSocket, and the reader should check the reference manual for details. In C, things are a bit more complex. The operation socket() takes three arguments, as follows. The first, domain, specifies the protocol family that will be used. In the above example, I use PF_INET, which is what you would use in most scenarios2. The second argument, type, indicates the semantics of the communication. Above, SOCK_STREAM is used to denote a byte stream. An alternative is SOCK_DGRAM which stands for a message-oriented service, such as that provided by UDP. The last argument, protocol, names the specific protocol that will be used. Above, I state IPPROTO_TCP but I could have used UNSPEC, for unspecified, because the combination of PF_INET and SOCK_STREAM implies TCP. The return value is a handle or descriptor for the

Note that PF_INET and AF_INET are often confused, but luckily both have the same numeric value (2).

Appendix B

Network Programming

341

newly created socket. This is an identifier by which we can refer to the socket in the future. As can be seen, it is given as an argument to subsequent operations on this socket. On a server machine, the application process performs a passive openthe server says that it is prepared to accept connections, but it does not actually establish a connection. The servers address and port number should be known in advance and, when the server program is run, it will ask the operating system to associate an (address, port number) pair with it, which is accomplished by the operation bind(). This resembles a server person requesting a phone company to assign to him/her a particular phone number. The phone company would either comply or deny if the number is already taken. The operation listen() then sets the capacity of the queue holding new connection attempts that are waiting to establish a connection. The server completes passive open by calling accept(), which blocks and waits for client calls. When a client connects, accept() returns a new socket descriptor, s_sock. This is the actual socket that is used in client/server exchanges. The well-known socket, rv_sock, is reserved as a meeting place for associating server with clients. Notice that accept() also gives back the clients address in struct sockaddr_in cli_addr. This is useful if server wants to decide whether or not it wants to talk to this client (for security reasons). This is optional and you can pass NULL for the last two arguments (see the server C code below). The reader should also notice that in C data types may be represented using different byte order (most-significant-byte-first, vs. least-significant-byte-first) on different computer architectures (e.g., UNIX vs. Windows). Therefore the auxiliary routines htons()/ntohs() and htonl()/ntohl() should be used to convert 16- and 32-bit quantities, respectively, between network byte order and host byte order. Because Java is platform-independent, it performs these functions automatically. Client application process, which is running on the client machine, performs an active openit proactively establishes connection to the server by invoking the connect() operation: Opening a TCP CLIENT socket in Java vs. C (Active Open)
import java.net.Socket; #include <arpa/inet.h> #include <sys/socket.h> #include <netdb.h> #define HOST "eden.rutgers.edu" #define PORT_NUM 4999

public static final String HOST = "eden.rutgers.edu"; public static final int PORT_NUM = 4999; Socket c_sock = new Socket(HOST, PORT_NUM);

int c_sock; struct hostent *serverIP; struct sockaddr_in serv_addr; serverIP = gethostbyname(HOST); serv_addr.sin_family = AF_INET; serv_addr.sin_addr.s_addr = // ... copy from: serverIP->h_addr ... serv_addr.sin_port = htons(port_num); c_sock = connect(c_sock, (struct sockaddr *) &serv_addr, sizeof(serv_addr));

Ivan Marsic

Rutgers University

342

Notice that, whereas a server listens for clients on a well-known port, a client typically does not care which port it uses for itself. Recall that, when you call a friend, you should know his/her phone number to dial it, but you need not know your number.

B.2 Example Java Client/Server Application

The following client/server application uses TCP protocol for communication. It accepts a single line of text input at the client side and transmits it to the server, which prints it at the output. It is a single-shot connection, so the server closes the connection after every message. To deliver a new message, the client must be run anew. Notice that this is a sequential server, which serves clients one-by-one. When a particular client is served, any other client attempting to connect will be placed in a waiting queue. To implement a concurrent server, which can serve multiple clients in parallel, you should use threads (see Section 4.3). The reader should consult Figure B-1 as a roadmap to the following code. Listing B-1: A basic SERVER application in Java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 import import import import import import import java.io.BufferedReader; java.io.IOException; java.io.InputStreamReader; java.io.OutputStreamWriter; java.io.PrintWriter; java.net.ServerSocket; java.net.Socket;

public class BasicServer { public static void main(String[] args) { if (args.length != 1) { // Test for correct num. of arguments System.err.println( "ERROR server port number not given"); System.exit(1); } int port_num = Integer.parseInt(args[0]); ServerSocket rv_sock = null; try { new ServerSocket(port_num); } catch (IOException ex) { ex.printStackTrace(); } while (true) { // run forever, waiting for clients to connect System.out.println("\nWaiting for client to connect..."); try { Socket s_sock = rv_sock.accept(); BufferedReader in = new BufferedReader( new InputStreamReader(s_sock.getInputStream()) ); PrintWriter out = new PrintWriter( new OutputStreamWriter(s_sock.getOutputStream()), true); System.out.println(

Appendix B

Network Programming

343

32 33 34 35 36 37 39

"Client's message: " + in.readLine()); out.println("I got your message"); s_sock.close(); } catch (IOException ex) { ex.printStackTrace(); } } } }

The code description is as follows: Lines 17: make available the relevant class files. Lines 914: define the server class with only one method, main(). The program accepts a single argument, the servers port number (1024 65535, for non-reserved ports). Line 15: convert the port number, input as a string, to an integer number. Lines 1619: create the well-known server socket. According to the javadoc of ServerSocket, the default value for the backlog queue length for incoming connections is set to 50. There is a constructor which allows you to set different backlog size. Line 24: the server blocks and waits indefinitely until a client makes connection at which time a Socket object is returned. Lines 2527: set up the input stream for reading clients requests. The actual TCP stream, obtained from the Socket object by calling getInputStream() generates a stream of binary data from the socket. This can be decoded and displayed in a GUI interface. Because our simple application deals exclusively with text data, we wrap a BufferedReader object around the input stream, in order to obtain buffered, character-oriented output. Lines 2830: set up the output stream for writing servers responses. Similar to the input stream, we wrap a PrintWriter object around the binary stream object returned by getOutputStream(). Supplying the PrintWriter constructor with a second argument of true causes the output buffer to be flushed for every println() call, to expedite the response delivery to the client. Lines 3132: receive the clients message by calling readLine() on the input stream. Line 33: sends acknowledgement to the client by calling println() on the output stream. Line 34: closes the connection after a single exchange of messages. Notice that the wellknown server socket rv_sock remains open, waiting for new clients to connect. The following is the client code, which sends a single message to the server and dies. Listing B-2: A basic CLIENT application in Java
1 2 3 4 5 6 7 8 import import import import import import java.io.BufferedReader; java.io.IOException; java.io.InputStreamReader; java.io.OutputStreamWriter; java.io.PrintWriter; java.net.Socket;

public class BasicClient {

Ivan Marsic

Rutgers University

344

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

public static void main(String[] args) { if (args.length != 2) { // Test for correct num. of arguments System.err.println( "ERROR server host name AND port number not given"); System.exit(1); } int port_num = Integer.parseInt(args[1]); try { Socket c_sock = new Socket(args[0], port_num); BufferedReader in = new BufferedReader( new InputStreamReader(c_sock.getInputStream()) ); PrintWriter out = new PrintWriter( new OutputStreamWriter(c_sock.getOutputStream()), true); BufferedReader userEntry = new BufferedReader( new InputStreamReader(System.in) ); System.out.print("User, enter your message: "); out.println(userEntry.readLine()); System.out.println("Server says: " + in.readLine()); c_sock.close(); } catch (IOException ex) { ex.printStackTrace(); } System.exit(0); } }

The code description is as follows: Lines 16: make available the relevant class files. Lines 914: accept two arguments, the server host name and its port number. Line 15: convert the port number, input as a string, to an integer number. Line 18: simultaneously opens the clients socket and connects it to the server. Lines 1921: create a character-oriented input socket stream to read servers responses. Equivalent to the servers code lines 2527. Lines 2224: create a character-oriented output socket stream to write request messages. Equivalent to the servers code lines 2830. Lines 2527: create a character-oriented input stream to read users keyboard input from the standard input stream System.in. Line 29: sends request message to the server by calling println() on the output stream. Line 30: receives and displays the servers response by readLine() on the input stream. Line 31: closes the connection after a single exchange of messages. Line 33: client program dies.

Appendix B

Network Programming

345

B.3 Example Client/Server Application in C

Here I present the above Java application, now re-written in C. Recall that the TCP protocol is used for communication; a UDP-based application would look differently. The reader should consult Figure B-2 as a roadmap to the following code. Listing B-3: A basic SERVER application in C on Unix/Linux
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 #include #include #include #include <stdio.h> <stdlib.h> <string.h> <sys/socket.h> /* /* /* /* perror(), fprintf(), sprintf() */ for atoi() */ for memset() */ socket(), bind(), listen(), accept(), recv(), send(), htonl(), htons() */ /* for sockaddr_in */ /* for close() */

#include <arpa/inet.h> #include <unistd.h>

#define MAXPENDING 5 /* Max outstanding connection requests */ #define RCVBUFSIZE 256 /* Size of receive buffer */ #define ERR_EXIT(msg) { perror(msg); exit(1); } int main(int argc, char *argv[]) { int rv_sock, s_sock, port_num, msg_len; char buffer[RCVBUFSIZE]; struct sockaddr_in serv_addr; if (argc != 2) { /* Test for correct number of arguments */ char msg[64]; memset((char *) &msg, 0, 64); sprintf(msg, "Usage: %s server_port\n", argv[0]); ERR_EXIT(msg); } rv_sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP); if (rv_sock < 0) ERR_EXIT("ERROR opening socket"); memset((char *) &serv_addr, 0, sizeof(serv_addr)); port_num = atoi(argv[1]); /* First arg: server port num. */ serv_addr.sin_family = AF_INET; serv_addr.sin_addr.s_addr = htonl(INADDR_ANY); serv_addr.sin_port = htons(port_num); if (bind(rv_sock, (struct sockaddr *) &serv_addr, sizeof(serv_addr)) < 0) ERR_EXIT("ERROR on binding"); if (listen(rv_sock, MAXPENDING) < 0) ERR_EXIT("ERROR on listen"); while ( 1 ) { /* Server runs forever */ fprintf(stdout, "\nWaiting for client to connect...\n"); s_sock = accept(rv_sock, NULL, NULL); if (s_sock < 0) ERR_EXIT("ERROR on accept new client"); memset(buffer, 0, RCVBUFSIZE); msg_len = recv(s_sock, buffer, RCVBUFSIZE - 1, 0); if (msg_len < 0) ERR_EXIT("ERROR reading from socket"); fprintf(stdout, "Client's message: %s\n", buffer);

Ivan Marsic

Rutgers University

346

46 47 48 49 50 51

msg_len = send(s_sock, "I got your message", 18, 0); if (msg_len < 0) ERR_EXIT("ERROR writing to socket"); close(s_sock); } /* NOT REACHED, because the server runs forever */ }

The code description is as follows: Lines 17: import the relevant header files. Lines 910: define the relevant constants. Line 11: defines an inline function to print error messages and exit the program. Line 13: start of the program. Line 14: declares the variables for two socket descriptors, well-known (rv_sock) and client-specific (s_sock), as well as servers port number (port_num) and message length, in bytes (msg_len) that will be used below. Line 15: Line 39: accepts new client connections and returns the socket to be used for message exchanges with the client. Notice that NULL is passed for the last two arguments, because this server is not interested in the clients address. Line 42: receive up to the buffer size (minus 1 to leave space for a null terminator) bytes from the sender. The input parameters are: the active socket descriptor, a char buffer to hold the received message, the size of the receive buffer (in bytes), and any flags to use. If no data has arrived, recv() blocks and waits until some arrives. If more data has arrived than the receive buffer can hold, recv() removes only as much as fits into the buffer. NOTE: This simplified implementation may not be adequate for general cases, because recv() may return a partial message. Remember that TCP connection provides an illusion of a virtually infinite stream of bytes, which is randomly sliced into packets and transmitted. The TCP receiver may call the application immediately upon receiving a packet. Suppose a sender sends M bytes using send( , , M, ) and a receiver calls recv( , , N, ), where M N. Then, the actual number of bytes K returned by recv() may be less than the number sent, i.e., K M. A simple solution for getting complete messages is for sender to preface all messages with a header indicating the message length. Then, the receiver finds the message length from the header and may need to call recv() repeatedly, while keeping a tally of received fragments, until the complete message is read. Line 46: sends acknowledgement back to the client. The return value indicates the number of bytes successfully sent. A return value of 1 indicates locally detected errors only (not network ones). Line 48: closes the connection after a single exchange of messages. Notice that the wellknown server socket rv_sock remains open, waiting for new clients to connect. Notice that this is a sequential server, which serves clients one-by-one. When a particular client is served, any other client attempting to connect will be placed in a waiting queue. The capacity of

Appendix B

Network Programming

347

the queue is limited by MAXPENDING and declared by invoking listen(). To implement a concurrent server, which can serve multiple clients in parallel, you should use threads (see Section 4.3). Listing B-4: A basic CLIENT application in C on Unix/Linux
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 50 51 #include #include #include #include <stdio.h> <stdlib.h> <string.h> <sys/socket.h> /* /* /* /* for perror(), fprintf(), sprintf() */ for atoi() */ for memset(), memcpy(), strlen() */ for sockaddr, socket(), connect(), recv(), send(), htonl(), htons() */ /* for sockaddr_in */ /* for hostent, gethostbyname() */ /* for close() */

#include <arpa/inet.h> #include <netdb.h> #include <unistd.h>

#define RCVBUFSIZE 256 /* Size of receive buffer */ #define ERR_EXIT(msg) { perror(msg); exit(1); } int main(int argc, char *argv[]) { int c_sock, port_num, msg_len; struct sockaddr_in serv_addr; struct hostent *serverIP; char buffer[RCVBUFSIZE]; if (argc != 3) { /* Test for correct number of arguments */ char msg[64]; memset((char *) &msg, 0, 64); /* erase */ sprintf(msg, "Usage: %s serv_name serv_port\n", argv[0]); ERR_EXIT(msg); } serverIP = gethostbyname(argv[1]); /* 1st arg: server name */ if (serverIP == NULL) ERR_EXIT("ERROR, server host name unknown"); port_num = atoi(argv[2]); /* Second arg: server port num. */ c_sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP); if (c_sock < 0) ERR_EXIT("ERROR opening socket"); memset((char *) &serv_addr, 0, sizeof(serv_addr)); serv_addr.sin_family = AF_INET; memcpy((char *) &serv_addr.sin_addr.s_addr, (char *) &(serverIP->h_addr), serverIP->h_length); serv_addr.sin_port = htons(port_num); if (connect(c_sock, (struct sockaddr *) &serv_addr, sizeof(serv_addr)) < 0) ERR_EXIT("ERROR connecting"); fprintf(stdout, "User, enter your message: "); memset(buffer, 0, RECVBUFSIZE); /* erase */ fgets(buffer, RECVBUFSIZE, stdin); /* read input */ msg_len = send(c_sock, buffer, strlen(buffer), 0); if (msg_len < 0) ERR_EXIT("ERROR writing to socket"); memset(buffer, 0, RECVBUFSIZE); msg_len = recv(c_sock, buffer, RECVBUFSIZE - 1, 0); if (msg_len < 0) ERR_EXIT("ERROR reading from socket"); fprintf(stdout, "Server says: %s\n", buffer); close(c_sock); exit(0);

Ivan Marsic

Rutgers University

348

52

The code description is as follows: Lines 18: import the relevant header files. Line 43: writes the users message to the socket; equivalent to line 46 of server code. Line 46: reads the servers response from the socket; equivalent to line 42 of server code.

I tested the above programs on Linux 2.6.14-1.1637_FC4 (Fedora Core 4) with GNU C compiler gcc version 4.0.1 (Red Hat 4.0.1-5), as follows: Step 1: Compile the server using the following command line:
% gcc -o server server.c

On Sun Microsystemss Solaris, I had to use:

% gcc -g -I/usr/include/ -lsocket -o server server.c

Step 2: Compile the client using the following command line:

% gcc -o client client.c

On Sun Microsystemss Solaris, I had to use:

% gcc -g -I/usr/include/ -lsocket -lnsl -o client client.c

Step 3: Run the server on the machine called caipclassic.rutgers.edu, with server port 5100:
% ./server 5100

Step 4: Run the client

% ./client caipclassic.rutgers.edu 5100

The server is silently running, while the client will prompt you for a message to type in. Once you hit the Enter key, the message will be sent to the server, the server will acknowledge the receipt, and the client will print the acknowledgment and die. Notice that the server will continue running, waiting for new clients to connect. Kill the server process by pressing simultaneously the keys Ctrl and c.

B.4 Windows Socket Programming

Finally, I include also the server version for Microsoft Windows: Listing B-5: A basic SERVER application in C on Microsoft Windows
1 2 3 4 5 6 #include <stdio.h> #include <winsock2.h> #define MAXPENDING 5 #define RCVBUFSIZE 256 #define ERR_EXIT { \ /* for all WinSock functions */ /* Max outstanding connection requests */ /* Size of receive buffer */

Appendix B

Network Programming

349

7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

fprintf(stderr, "ERROR: %ld\n", WSAGetLastError()); \ WSACleanup(); return 0; } int main(int argc, char *argv[]) { WSADATA wsaData; SOCKET rv_sock, s_sock; int port_num, msg_len; char buffer[RCVBUFSIZE]; struct sockaddr_in serv_addr; if (argc != 2) { /* Test for correct number of arguments */ fprintf(stdout, "Usage: %s server_port\n", argv[0]); return 0; } WSAStartup(MAKEWORD(2,2), &wsaData);/* Initialize Winsock */ rv_sock = WSASocket(PF_INET, SOCK_STREAM, IPPROTO_TCP, NULL, 0, WSA_FLAG_OVERLAPPED); if (rv_sock == INVALID_SOCKET) ERR_EXIT; memset((char *) &serv_addr, 0, sizeof(serv_addr)); port_num = atoi(argv[1]); /* First arg: server port num. */ serv_addr.sin_family = AF_INET; serv_addr.sin_addr.s_addr = inet_addr("127.0.0.1"); serv_addr.sin_port = htons(port_num); if (bind(rv_sock, (SOCKADDR*) &serv_addr, sizeof(serv_addr)) == SOCKET_ERROR) { closesocket(rv_sock); ERR_EXIT; } if (listen(rv_sock, MAXPENDING) == SOCKET_ERROR) { closesocket(rv_sock); ERR_EXIT; } while ( 1 ) { /* Server runs forever */ fprintf(stdout, "\nWaiting for client to connect...\n"); if (s_sock = accept(rv_sock, NULL, NULL) == INVALID_SOCKET) ERR_EXIT; memset(buffer, 0, RCVBUFSIZE); msg_len = recv(s_sock, buffer, RCVBUFSIZE - 1, 0); if (msg_len == SOCKET_ERROR) ERR_EXIT; fprintf(stdout, "Client's message: %s\n", buffer); msg_len = send(s_sock, "I got your message", 18, 0); if (msg_len == SOCKET_ERROR) ERR_EXIT; closesocket(s_sock); } return 0; }

The reader should seek further details on Windows sockets here: http://msdn.microsoft.com/library/en-us/winsock/winsock/windows_sockets_start_page_2.asp.

Ivan Marsic

Rutgers University

350

Bibliographical Notes
[Stevens et al., 2004] remains the most authoritative guide to network programming. A good quick guides are [Donahoo & Calvert, 2001] for network programming in the C programming language and [Calvert & Donahoo, 2002] for network programming in the Java programming language. There are available many online tutorials for socket programming. Java tutorials include Sun Microsystems, Inc., http://java.sun.com/docs/books/tutorial/networking/sockets/index.html Qusay H. Mahmoud, Sockets programming in Java: A tutorial, http://www.javaworld.com/jw-12-1996/jw-12-sockets.html Sockets Tutorial, http://www.cs.rpi.edu/courses/sysprog/sockets/sock.html Peter Burden, Sockets Programming, http://www.scit.wlv.ac.uk/~jphb/comms/sockets.html Beejs Guide to Network Programming Using Internet Sockets, http://beej.us/guide/bgnet/ also at http://mia.ece.uic.edu/~papers/WWW/socketsProgramming/html/index.html Microsoft Windows Sockets Getting Started With Winsock, http://msdn.microsoft.com/library/en-us/winsock/winsock/getting_started_with_winsock.asp

and C tutorials include

Davin Milun maintains a collection of UNIX programming links at http://www.cse.buffalo.edu/~milun/unix.programming.html. UNIX sockets library manuals can be found at many websites, for example here: http://www.opengroup.org/onlinepubs/009695399/mindex.html. Information about Windows Sockets for Microsoft Windows can be found here: http://msdn.microsoft.com/library/en-us/winsock/winsock/windows_sockets_start_page_2.asp.

HTTP Overview

Appendix C

The Hypertext Transfer Protocol (HTTP) is an application-level protocol underlying the World Wide Web. HTTP is implemented using a very simple RPC-style interface, in which all messages are represented as human-readable ASCII strings, although often containing encoded or even encrypted information. It is a request/response protocol in that a client sends a request to the server and the server replies with a response as follows (see Figure C-1): Client Request Server Response A request method Protocol version URI (Uniform Resource Identifier) A success or error code Protocol version A MIME-like message containing server A MIME-like message containing request information, entity meta-information, and modifiers, client information, and possibly possibly entity-body content body content To quickly get an idea of what is involved here, I suggest you perform the following experiment. On a command line of a UNIX/Linux shell or a Windows Command Prompt, type in as follows:
% telnet www.wired.com 80

The Telnet protocol will connect you to the Wired magazines web server, which reports:
Trying 209.202.230.60...

Client Request Message

Client

GET /index.html HTTP 1.1 Accept: image/gif, image/x-xbitmap, image/ jpeg, image pjpeg, */* Accept-Language: en-us Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible, MSIE 5.01; Windows NT) Host: caip.rutgers.edu Connection: Keep-Alive

Server

Time

HTTP/1.1 200 OK Date: Thu, 23 Feb 2006 21:03:56 GMT Server: Apache/2.0.48 (Unix) DAV/2 PHP/4.3.9 Last-Modified: Thu, 18 Nov 2004 16:40:02 GMT ETag: "1689-10a0-aab5c80" Accept-Ranges: bytes Content-Length: 4256 Connection: close Content-Type: text/html; charset=ISO-8859-1 <HTML> <HEAD> <TITLE>CAIP Center-Rutgers University</TITLE> </HEAD>

Server Response Message

Figure C-1: Example HTTP request/response transaction.

351

Ivan Marsic

Rutgers University

352

Connected to www.wired.com. Escape character is '^]'.

Then type in the HTTP method to download their web page:

GET / HTTP/1.0

Hit the Enter key (carriage return + line feed) twice and you will get back the HTML document of the Wired home page. You can also try the same with the method HEAD instead of GET, as well as with other methods introduced later, including their header fieldsjust remember to terminate the request with a blank line. Early versions of HTTP dealt with URLs, but recently the concept of URI (see RFC 2396 http://www.ietf.org/rfc/rfc2396.txt)a combination of URL and URN (Unified Resource Name)has become popular to express the idea that the URL may be a locator but may also be the name of an application providing a service, indicating the form of abstract resource that can be accessed over the Web. A resource is anything that has a URI. A URI begins with a specification of the scheme used to access the item. The scheme is usually named after the transfer protocol used in accessing the resource, but the reader should check details in RFC 2396). The format of the remainder of the URI depends on the scheme. For example, a URI that follows the http scheme has the following format: http: // hostname [: port] / path [; parameters] [? query] where italic signifies an item to be supplied, and brackets denote an optional item. The hostname string is a domain name of a network host, or its IPv4 address as a set of four decimal digit groups separated by dots. The optional :port is the network port number for the server, which needs to be specified only if server does not use the well-known port (80). The /path string identifies single particular resource (document) on the server. The optional ;parameters string specifies the input arguments if the resource is an application, and similar for ?query. Ordinary URLs, which is what you will most frequently see, contain only hostname and path. An entity is the information transferred as the payload of a request or response. It consists of meta-information in the form of entity-header fields and optional content in the form of an entitybody. For example, an entity-body is the content of the HTML document that the server returns upon clients request, as in Figure C-1.

C.1 HTTP Messages

HTTP messages are either requests from client to server or responses from server to client. Both message types consist of A start line, Request-Line or Status-Line One or more header fields, including General header, request header, response header, and entity header fields

Appendix C

HTTP Overview

353

Each header field consists of a name (case insensitive), followed by a colon (:) and the field value An empty line indicating the end of the header fields. The end-of-header is defined as the sequence CR-LF-CR-LF (double newline, written in C/C++/Java as "\r\n\r\n") An optional message body, used to carry the entity body (a document) associated with a request or response.

Encoding mechanisms can be applied to the entity to reduce consumption of scarce resources. For example, large files may be compressed to reduce transmission time over slow network connections. Encoding mechanisms that are defined are gzip (or x-gzip), compress (or x-compress), and deflate (the method found in PKWARE products). HTTP operates over a TCP connection. Original HTTP was stateless, meaning that a separate TCP connection had to be opened for each request performed on the server. This resulted in various inefficiencies, and the new design can keep connection open for multiple requests. In normal use, the client sends a series of requests over a single connection and receives a series of responses back from the server, leaving the connection open for a while, just in case it is needed again. HTTP also permits a server to return a sequence of responses with the intent of supporting the equivalent of news-feed or a stock ticker. This section reviews the request and response messages. Message headers are considered in more detail in Section C.2.

HTTP Requests
An HTTP request consists of (see Figure C-2) A request line containing the HTTP method to be applied to the resource, the URI of the resource, and the protocol version in use A general header A request header An entity header An empty line (to indicate the end of the header) A message body carrying the entity body (a document)

Ivan Marsic

Rutgers University

354

Request method

Resource URI

Protocol version

Request line

Empty line (indicates end-of-header)

GET /index.html HTTP 1.1 Accept: image/gif, image/x-xbitmap, image/ jpeg, image pjpeg, */* Accept-Language: en-us Accept-Encoding: gzip, deflate User-Agent: Mozilla/5.0 (compatible, MSIE 5.01; Windows NT) Host: caip.rutgers.edu Connection: Keep-Alive

Entity header field

Figure C-2: HTTP Request message format. As seen in Figures C-2 and C-3, different headers can be interleaved and the order of the header fields is not important. The following is the table of HTTP methods: Method Description GET Retrieves a resource on the server identified by the URI. This resource could be the contents of a static file or invoke a program that generates data. HEAD Retrieves only the meta-information about a document, not the document itself. Typically used to test a hypertext link for validity or to obtain accessibility and modification information about a document. PUT Requests that the server store the enclosed entity, which represents a new or replacement document. POST Requests that the server accept the enclosed entity. Used to perform a database query or another complex operation, see below. DELETE Requests that the server removes the resource identified by the URI. TRACE Asks the application-layer proxies to declare themselves in the message headers, so the client can learn the path that the document took. OPTIONS Used by a client to learn about other methods that can be applied to the specified document. CONNECT Used when a client needs to talk to a server through a proxy server. There are several more HTTP methods, such as LINK, UNLINK, and PATCH, but they are less clearly defined.

Request header fields

Appendix C

HTTP Overview
Status code (success or error)

355

Protocol version

Status line

Empty line (indicates end-of-header)

HTTP 1.1 200 OK Date: Thu, 23 Feb 2006 21:03:56 GMT Server: Apache/2.0.48 (Unix) DAV/2 PHP/4.3.9 Last-Modified: Thu, 18 Nov 2004 16:40:02 GMT ETag: "1689-10a0-aab5c80" Accept-Ranges: bytes Content-Length: 4256 Connection: close Content-Type: text/html; charset=ISO-8859-1 <HTML> <HEAD> <TITLE>CAIP Center-Rutgers University</TITLE> </HEAD> ...

General header fields

Response header fields

Entity header fields

Entity body

Figure C-3: HTTP Response message format. The GET method is used to retrieve a document from a Web server. There are some special cases in which GET behaves differently. First, a server may construct a new HTML document for each request. These are handled by specifying a URI that identifies a program in a special area on the Web server known as the cgi-bin area. The URI also includes arguments to the program in the path name suffix. Many fill-form requests associated with Web pages use this approach instead of a POST method, which is somewhat more complex. A second special case arises if a document has moved. In this case, the GET method can send back a redirection error code that includes the URI of the new location. The POST method is used for annotating existing resourcesthe client posts a note to the resource. Examples include posting of a conventional message to an e-mail destination, bulleting board, mailing list, or chat session; providing a block of data obtained through a fill-form; or extending a database or file through an append operation.

HTTP Responses
An HTTP response consists of (see Figure C-3) A status line containing the protocol version and a success or error code A general header A response header An entity header An empty line (to indicate the end of the header) A message body carrying the entity body (a document)

Among these only the status-line is required. The reader should consult the standard for the interpretation of the numeric status codes. The response header fields will be described later.

Ivan Marsic

Rutgers University

356

C.2 HTTP Message Headers

HTTP transactions do not need to use all the headers. In fact, in HTTP 1.0, only the request line is required and it is possible to perform some requests without supplying header information at all. For example, in the simplest case, a request of GET /index.html HTTP/1.0 without any headers would suffice for most web servers to understand the client. In HTTP 1.1, a Host request header field is the minimal header information required for a request message.

General Headers
General-header fields apply to both request and response messages. They indicate general information such as the current time or the path through the network that the client and server are using. This information applies only to the message being transmitted and not to the entity contained in the message. General headers are as follows: Header Description Cache-Control Specifies desired behavior from a caching system, as used in proxy servers. Directives such as whether or not to cache, how long, etc. Connection Specifies whether a particular connection is persistent or automatically closed after a transaction. Date Contains the date and time at which the message was originated. Pragma Specifies directives for proxy and gateway systems; used only in HTTP 1.0 and maintained in HTTP 1.1 for backwards compatibility. Trailer Specifies the headers in the trailer after a chunked message; not used if no trailers are present. TransferIndicates what, if any, type of transformation has been applied to the Encoding message, e.g., chunked. (This is not the same as content-encoding.) Upgrade Lists what additional communication protocols a client supports, and that it would prefer to talk to the server with an alternate protocol. Via Updated by gateways and proxy servers to indicate the intermediate protocols and hostname. This information is useful for debugging process. Warning Carries additional information about the status or transformation of a message which might not be reflected in the message, for use by caching proxies.

Request Headers
The request-header fields allow the client to pass additional information about the request, and about the client itself, to the server. These fields act as request modifiers, with semantics equivalent to the parameters/arguments of a programming language method invocation. Request headers are listed in this table: Header Description Accept Specifies content encodings of the response that the client prefers. Accept-Charset Specifies the character sets that the client prefers. If this header is not specified, the server assumes the default of US-ASCII and ISO-8859-1. Accept-Encoding Specifies content encoding algorithms that the client understands. If this

Appendix C

HTTP Overview

357

Accept-Language

Authorization Expect TransferEncoding From Host If-Match If-ModifiedSince If-None-Match If-Range If-UnmodifiedSince Max-Forwards ProxyAuthorization Range Referer TE

header is omitted, the server will send the requested entity-body as-is, without any additional encoding. Specifies human language(s) that the client prefers. Languages are represented by their two-letter abbreviations, such as en for English, fr for French, etc. Provides the user agents credentials to access data at the URI. Sent in reaction to WWW-Authenticate in a previous response message. Indicates what specific server behaviors are required by the client. If the server is incapable of the expectation, it returns an error status code. Indicates what, if any, type of transformation has been applied to the message. Contains an Internet e-mail address for the user executing the client. For the sake of privacy, this should not be sent without the users consent. Specifies the Internet hostname and port number of the server contacted by the client. Allows multihomed servers to use a single IP address. A conditional requesting the entity only if it matches the given entity tag (see the ETag entity header). Specifies that the Request-URI data is to be returned only if ith has been modified since the supplied date and time (used by GET method). Contains the condition to be used by an HTTP method. A conditional requesting only a missing portion of the entity, if it has not been changed, and the entire entity if it has (used by GET method). A conditional requesting the entity only if it has been modified since a given date and time. Limits the number of proxies or gateways that can forward the request. Allows the client to identify itself to a proxy requiring authentication. Requests a partial range from the entity body, specified in bytes. Gives the URI of the resource from which the Request-URI was obtained. Indicates what extension transfer-encodings the client is willing to accept in the response and whether or not it is willing to accept trailer fields in a chunked transfer-coding. Contains info about the client application originating the request.

User-Agent

A user agent is a browser, editor, or other end-user/client tool.

Response Headers
The response-header fields are used only in server response messages. They describe the servers configuration and information about the requested URI resource. Response headers are as follows: Header Description Accept-Ranges Indicates the servers acceptance of range requests for a resource, specifying either the range unit (e.g., bytes) or none if no range requests are accepted. Age Contains an estimate of the amount of time, in seconds, since the response was generated at the origin server. ETag Provides the current value of the entity tag for the requested variant of the given document for the purpose of cache management (see below).

Ivan Marsic

Rutgers University

358

Location

ProxyAuthenticate Retry-After

Server Set-Cookie Vary WWWAuthenticate

Specifies the new location of a document; used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. Indicates the authentication scheme and parameters applicable to the proxy for this Request-URI and the current connection. Indicates how long the service is expected to be unavailable to the requesting client. Given in seconds or as a date and time when a new request should be placed. Contains information about the software used by the origin server to handle the requestname and version number. Contains a (name, value) pair of information to retain for this URI; for browsers supporting cookies. Signals that the response entity has multiple sources and may therefore vary; the response copy was selected using server-driven negotiation. Indicates the authentication scheme and parameters applicable to the URI.

Entity tags are unique identifiers of different versions of the document that can be associated with all copies of the document. By checking the ETag header, the client can determine whether it already has a copy of the document in its local cache. If the document is modified, its entity tag changes, so it is more efficient to check for the entity tag than Last-Modified date.

Entity Headers
Entity-header fields define metainformation about the entity-body or, if no body is present, about the resource identified by the request. They specify information about the entity, such as length, type, origin, and encoding schemes. Although entity headers are most commonly used by the server when returning a requested document, they are also used by clients when using the POST or PUT methods. Entity headers are as follows: Header Description Allow Lists HTTP methods that are allowed at a specified URL, such as GET, POST, etc. ContentIndicates what additional content encodings have been applied to the Encoding entity body, such as gzip or compress. ContentSpecifies the human language(s) of the intended audience for the entity Language body. Languages are represented by their two-letter abbreviations, such as en for English, fr for French, etc. Content-Length Indicates the size, in bytes, of the entity-body transferred in the message. ContentSupplies the URL for the entity, in cases where a document has multiple Location entities with separately accessible locations. Content-MD5 Contains an MD5 digest of the entity body, for checking the integrity of the message upon receipt. Content-Range Sent with a partial entity body to specify where the partial body should be inserted in the full entity body. Content-Type Indicates the media type and subtype of the entity body. It uses the same values as the clients Accept header. Example: text/html Expires Specifies the date and time after which this response is considered stale. Last-Modified Contains the date and time at which the origin server believes the resource was last modified.

Appendix C

HTTP Overview

359

C.3 HTTPSSecure HTTP

HTTPS (Hypertext Transfer Protocol over Secure Socket Layer, or HTTP over SSL) is a Web protocol developed by Netscape and built into its browser that encrypts and decrypts user page requests as well as the pages that are returned by the Web server. Technically, HTTPS sends normal HTTP messages through a SSL sublayer. SSL is a generic technology that can be used to encrypt many different protocols; hence HTTPS is merely the application of SSL to the HTTP protocol. HTTPS server listens by default on the TCP port 443 while HTTP uses the TCP port 80. SSL key size is usually either 40 or 128 bits for the RC4 stream encryption algorithm, which is considered an adequate degree of encryption for commercial exchange. When the URI schema of the resource you pointed to starts with https:// and you click Send, your browsers HTTPS layer will encrypt the request message. The response message you receive from the server will also travel in encrypted form, arrive with an https:// URI, and be decrypted for you by your browsers HTTPS sublayer.

Bibliographical Notes
Above I provide only a brief summary of HTTP, and the interested reader should seek details online at http://www.w3.org/Protocols/. A comprehensive and highly readable coverage of HTTP is given in [Krishnamurthy & Rexford, 2001]. The interested reader should check IETF RFC 2660: The Secure HyperText Transfer Protocol at http://www.ietf.org/rfc/rfc2660.txt, and the related RFC 2246: The TLS Protocol Version 1.0, which is updated in RFC 3546.

Database-Driven Web Applications

Appendix D

Typical web application is a web-based user interface on a relational database.

Bibliographical Notes
T. Coatta, Fixated on statelessness, ACM Queue, May http://www.acmqueue.com/modules.php?name=News&file=article&sid=361 15, 2006. Online at:

P. Barry, A database-driven Web application in 18 lines of code, Linux Journal, no. 131, pp. 54-61, March 2005, Online at: http://www.linuxjournal.com/article/7937

360

Document Object Model (DOM)

Appendix E

The purpose of Document Object Model (DOM) is to allow programs and scripts running in a web client (browser) to access and manipulate the structure and content of markup documents. DOM also allows the creation of new documents programmatically, in the working memory. DOM assumes a hierarchical, tree data-structure of documents and it provides platform-neutral and language-neutral APIs to navigate and modify the tree data-structure. If documents are becoming applications, we need to manage a set of user-interactions with a body of information. The document thus becomes a user-interface to information that can change the information and the interface itself. When the XML processor parses an XML document, in general it produces as a result a representation that is maintained in the processors working memory. This representation is usually a tree data structure, but not necessarily so. DOM is an abstraction, or a conceptual model of how documents are represented and manipulated in the products that support the DOM interfaces. Therefore, in general, the DOM interfaces merely make it look as if the document representation is a tree data structure. Remember that DOM specifies only the interfaces without implying a particular implementation. The actual internal data structures and operations are hidden behind the DOM interfaces and could be potentially proprietary. The object model in the DOM is a programming object model that comes from object-oriented design (OOD). It refers to the fact that the interfaces are defined in terms of objects. The name Document Object Model was chosen because it is an object model in the traditional OOD sense: documents are modeled using objects, and the model encompasses the structure as well as the behavior of a document and the objects of which it is composed. As an object model, the DOM identifies: The interfaces and objects used to represent and manipulate a document The semantics of these interfaces and objects, including both behavior and attributes The relationships and collaborations among these interfaces and objects.

E.1 Core DOM Interfaces

361

Ivan Marsic

Rutgers University

362

Models are structures. The DOM closely resembles the structure of the documents it models. In the DOM, documents have a logical structure which is very much like a tree. Core object interfaces are sufficient to represent a document instance (the objects that occur within the document itself). The document can be HTML or XML documents. The main types of objects that an application program will encounter when using DOM include:

Node
The document structure model defines an object hierarchy made up of a number of nodes. The Node object is a single node on the document structure model and the Document object is the root node of the document structure model and provides the primary access to the document's data. The Document object provides access to the Document Type Definition (DTD) (and hence to the structure), if it is an XML document. It also provides access to the root level element of the document. For an HTML document, that is the <HTML> element, and in an XML document, it is the top-level element. It also contains the factory methods needed to create all the objects defined in an HTML or XML document. Each node of the document tree may have any number of child nodes. A child will always have an ancestor and can have siblings or descendants. All nodes, except the root node, will have a parent node. A leaf node has no children. Each node is ordered (enumerated) and can be named. The DOM establishes two basic types of relationships: 1. Navigation: The ability to traverse the node hierarchy, and 2. Reference: The ability to access a collection of nodes by name.

NAVIGATION The structure of the document determines the inheritance of element attributes. Thus, it is important to be able to navigate among the node objects representing parent and child elements. Given a node, you can find out where it is located in the document structure model and you can refer to the parent, child as well as siblings of this node. A script can manipulate, for example, heading levels of a document, by using these references to traverse up or down the document structure model. This might be done using the NodeList object, which represents an ordered collection of nodes. REFERENCE Suppose, for example, there is a showcase consisting of galleries filled with individual images. Then, the image itself is a class, and each instance of that class can be referenced. (We can assign a unique name to each image using the NAME attribute.) Thus, it is possible to create an index of image titles by iterating over a list of nodes. A script can use this relationship, for example, to reference an image by an absolute or relative position, or it might insert or remove an image. This might be done using the NamedNodeMap object, which represents (unordered) collection of nodes that can be accessed by name.

Appendix E

Document Object Model (DOM)

363

Element
Element represents the elements in a document. (Recall that XML elements are defined in Section 6.1.1.) It contains, as child nodes, all the content between the start tag and the end tag of an element. Additionally, it has a list of Attribute objects, which are either explicitly specified or defined in the DTD with default values.

Document
Document represents the root node of a standalone document.

Bibliographical Notes
Document Object Model (DOM) Level 1 Specification, Version 1.0, W3C Recommendation 1 October, 1998. Online at: http://www.w3.org/TR/REC-DOM-Level-1/ DOM description can be found here: http://www.irt.org/articles/js143/index.htm

User Interface Programming

Appendix F

User interface design should focus on the human rather than on the system side. The designer must understand human fallibilities and anticipate them in the design. Understanding human psychology helps understand what it is that makes the user interface easier to understand, navigate, and use. Because proper treatment of these subjects would require a book on their own, I will provide only a summary of key points. Model/View/Controller design pattern is the key software paradigm to facilitate the construction of user interface software and is reviewed first.

F.1 Model/View/Controller Design Pattern

MVC pattern

F.2 UI Design Recommendations

Some of the common recommendations about interfaces include: Visibility: Every available operation/feature should be perceptible, either by being currently displayed or was recently shown so that it has not faded from users short-term memory. Visible system features are called affordances; Transparency: Expose the system state at every moment. For example, when using different tools in manipulation, it is common to change the cursor shape to make the user aware of the current manipulation mode (rotation, scaling, or such); Consistency: Whenever possible, comparable operations should be activated in the same way (although, see [Error! Reference source not found.] for some cautionary remarks). Or, stated equivalently, any interface objects that look the same are the same;

364

Appendix D

Document Object Model (DOM)

365

Reversibility: Include mechanisms to recover a prior state in case of user or system errors (for example, undo/redo mechanism). Related to this, user action should be interruptible, in case the user at any point changes their mind, and allowed to be redone; Intuitiveness: Design system behavior to minimize the amount of surprise experienced by the target user (here is where metaphors and analogies in the user interface can help); Guidance: Provide meaningful feedback when errors occur so the user will know what follow-up action to perform; also provide context-sensitive user help facilities.

Obviously, the software engineer should not adopt certain design just because it is convenient to implement. The human aspect of the interface must be foremost. Experience has shown that, although users tend at first to express preference for good looks, they eventually come around to value experience. The interface designer should, therefore, be more interested in how the interface feels, than in its aesthetics. What something looks like should come after a very detailed conversation about what it will do. There are different ways that interface developers quantify the feel of an interface, such as GOMS keystroke model, Fitts Law, Hicks Law, etc. [Raskin, 2000].

Bibliographical Notes
[Raskin, 2000], is mostly about interface design, little on software engineering, but articulates many sound design ideas for user interfaces. Some websites of interest (last checked August 2005): http://www.useit.com/ [useit.com: Jakob Nielsen on Usability and Web Design] http://www.jnd.org/ [Don Normans jnd website] http://www.asktog.com/ [AskTog: Interaction Design Solutions for the Real World] http://www.pixelcentric.net/x-shame/ [Pixelcentric Interface Hall of Shame] http://citeseer.ist.psu.edu/context/16132/0 http://www.sensomatic.com/chz/gui/Alternative2.html http://www.derbay.org/userinterfaces.html http://www.pcd-innovations.com/infosite/trends99.htm [Trends in Interface Designs (1999 and earlier)] http://www.devarticles.com/c/a/Java/Graphical-User-Interface/ http://www.chemcomp.com/Journal_of_CCG/Features/guitkit.htm

Solutions to Selected Problems

Problem 2.1 Solution

Problem 2.2 Solution

Problem 2.3 Solution

During a single sitting, the buyer (bidder) only can make a payment. A notification will be sent to the seller (auctioneer) about the successful payment and a request to ship the item. The subsequent activities of tracking the shipment and asking the buyer and seller to rate the transaction must happen in different sittings. Here shown is only the main success scenario.

Use Case UC-x:

Initiating Actor: Actors Goal: Preconditions:

BuyItem
Buyer To purchase auctioned item for which s/he won the bid & have it shipped Buyer has won the auction and has sufficient funds or credit line to pay for the item. Buyer is currently logged in the system and is shown a hyperlink Purchase this item. Seller has an account to receive payment. Seller already posted the invoice (including shipping and handling costs, optional insurance cost, etc.) and acceptable payment options, such as credit card, money order, PayPal.com, etc. Funds are transferred to the sellers account, minus selling fees. Seller is notified to ship the item. Auction is registered as concluded.

Participating Actors: Seller, Creditor

Postconditions:

Flow of Events for Main Success Scenario: 1. Buyer clicks the hyperlink Purchase this item 2. System displays the invoice from seller with acceptable payment options 3. Buyer selects the credit card payment method 4. System prompts for the credit card information 5. Buyer fills out the credit card information and submits it 6. System passes the card info and payment amount on to Creditor for authorization 7. Creditor replies with the payment authorization message _ 8. System (a) credits the sellers account, minus a selling fee charge; (b) archives the transaction in a database and assigns it a control number; (c) registers the auction as

366

Solutions to Selected Problems

367

concluded; (d) informs Buyer of the successful transaction and its control number; and (e) sends notification to Seller about the payment and the shipment address

The above use case describes only the key points. In reality, the seller should also be asked for the shipping and billing address and to choose a shipping type. I am not familiar with how eBay.com implements this process, so the reader may wish to compare and explain the differences. Extensions (alternate scenarios) include: Buyer abandons the purchase or the time allowed for initiating this use case has expired Buyer selects different payment method, e.g., money order or PayPal.com account Buyer provides invalid credit card information Creditor denies the transaction authorization (insufficient funds, incorrect information) Internet connection is lost through the process

Problem 2.4 Solution

Problem 2.5 Solution

Surely several alternative design solutions are possible, but your basic question is: Does your design meet all the customers needs (as specified in the problem description)? Next, is it easy for the customer to understand that your design artifacts are indeed there to meet their needs?

(a) The Owner is the key actor, but the system is also activated by the motion detector and by the electric eye sensor. Additionally, we need a timer to schedule the automatic switching off the light. Hence, we have four actors: Owner, MotionDetector, Timer, and ElectricEye. Their goals will be explained below.

(b)

Ivan Marsic

Rutgers University

368

A possible use case diagram is shown in the following figure:

initiate

AutoLightON AutoLightOFF RemoteOpen

participate
te initia

MotionDetector

Timer

initiate

ManualOpen RemoteClose ManualClose AutomaticReverse

Owner

pate rtici pa participate in itiat e ElectricEye

As explained in Section 2.3, the system is always passive and must be provoked to respond. Hence, automatic switching the light on is represented as the use case initiated by the motion detectorthe motion detector literally operates the light. In this use case, the system starts the timer and after it counts down to zero, the timer switches the light off. The requirements also demand that door closing must include a safety feature of automatic reversal of the door movement. The actual initiator is the electric eye sensor, and for this purpose, we have the AutomaticReverse use case. For this to function, the system must arm the electric eye sensor in the use cases RemoteClose and ManualClose (indicated by the communication type participate). The electric eye sensor is armed only when the garage door closes and not when it opens. The AutomaticReverse use case can be represented as follows:

Use Case:
Initiating Actor: Actors Goal: Preconditions: Postconditions:

AutomaticReverse
ElectricEye (electric eye sensor) To stop and reverse the door movement if someone or something passes under the garage door while it closes. The garage door currently is going down and the infrared light beams have been sensed as obstructed. The doors downward motion is stopped and reversed.

Flow of Events for Main Success Scenario: 1. ElectricEye signals to the system that the infrared light beams have been sensed as obstructed 2. System (a) stops and reverses the motor movement, and (b) disarms the ElectricEye sensor 3. System detects that the door is in the uppermost position and stops the motor

Solutions to Selected Problems

369

A possible extension (alternate scenario) is that the communication between the system and the motor is malfunctioning and the door keeps moving downward. To detect this possibility, we would need to introduce an additional sensor to measure the door motion. Also, it should be noticed that we assume a simple Open use case, i.e., the opening operation does not include automatic close after the car passes through the door. (In case this was required, we would need to start another timer or a sensor to initiate the door closing.)

(c) The use diagram is shown in the part (b) above.

(d) For the use case RemoteOpen, the main success scenario may look something like this: 1. Owner arrives within the transmission range and clicks the open button on the remote controller 2. The identification code may be contained in the first message, or in a follow-up one 3. System (a) verifies that this is a valid code, (b) opens the lock, (c) starts the motor, and (d) signals to the user the code validity 4. System increments the motor in a loop until the door is completely open 5. User enters the garage Alternate scenarios include: The receiver cannot decode the message because the remote transmitter is not properly pointed for optimal transmission The remote controller sends an invalid code. In this and the previous case, the system should sound the alarm after the maximum allowed number of attempts is exhausted The Owner changes his/her mind and decides to close the door while it is still being opened

It is left to the reader to describe what exactly happens in these cases.

(e) System sequence diagram for RemoteOpen:

Ivan Marsic

Rutgers University

370

: System

: System

Owner
sendOpeningSignal(code) verify code

Owner
loop sendOpeningSignal(code) verify code

signal: valid code unlock, start the motor signal: invalid code alt numTrials <= maxTrials same as main success scenario increment the motor [else] sound alarm

loop

(a)
Main success scenario for RemoteOpen

(b)
An alternate scenario for RemoteOpen

(f) The domain model could be as follows:

Communicator obtains Code CodeStore

CodeChecker numTrials maxTrials notifies

notifiesCodeValidity

LockOperator lockStatus

MotorOperator motorStatus

notifiesCodeValidity

AlarmOperator

LightOperator lightStatus

controls

MotionDetector

(g) Operation contracts for RemoteOpen:

controls

conveysRequests

e rifi ve

dC Vali ves etrie

s ode

ElectricEye

Solutions to Selected Problems

371

Problem 2.6 Solution

The developers intent is to prevent the theft of code. Therefore, this is not a legitimate use case.

Problem 2.7: Restaurant Automation Solution

Brief use case descriptions are as follows. UC1: ClockIn Employee records the start time of his/her shift or upon arriving back from a lunch break, assuming, of course, that the employee clocked-out before going to lunch. UC2: ClockOut Employee records the end time of his/her shift or when going out for a lunch break. (The system could automatically log out the employee from any open sessions.) UC3: LogIn Employee logs-in to the system in order to perform his/her necessary functions. UC4: LogOut Employee logs-out of the system, including if another employee needs to use that terminal. UC5: MarkTableReady Busboy marks a table ready for use after it has been cleaned and prepared for a new party. The Host is automatically notified, so now they can seat a new customer party at this table. UC6: SeatTable Host seats a customer, marks the table as occupied and assigns a waiter to it. UC7: AddItem Waiter adds an item to a tables tab. UC8: RemoveItem Waiter removes an item from a tables tab that does not belong there. The Manager enters his/her authorization code to complete the item removal process. UC9: AdjustPrice Waiter adjusts the price of a menu item due to a coupon, promotion, or customer dissatisfaction. UC10: ViewTab Waiter views the current tab of a particular table. UC11: CloseTab Waiter indicates that a tab has been paid, and that the transaction is completed. The tables tabs values are reset to empty or 0 but the transaction is recorded in the database. The system automatically notifies the Busboy so that he/she can clean the dirty table. (There could be an intermediate step to wait until the party leaves their table and only then the Waiter to register a table as waiting to be cleared.) UC12: PlaceOrder Waiter indicates that a tables tab is completed. The kitchen staff (Cook) is notified that the order must be prepared. UC13: MarkOrderReady Cook announces the completion of an order. The status of the order tab is changed, the tab is removed from the order queue in the kitchen, and the appropriate Waiter is notified. UC14: EditMenu Manager modifies the parameters of a menu item (name, price, description, etc.) or add/removes an item to the menu. UC15: ViewStatistics Manager inspects the statistics of the restaurant.

Ivan Marsic

Rutgers University

372

Restaurant Automation System UC1: ClockIn UC2: ClockOut Employee UC3: LogIn UC4: LogOut include include Employee

UC5: MarkTableReady UC6: SeatTable Host UC7: AddItem UC8: RemoveItem UC9: AdjustPrice UC10: ViewTab UC11: CloseTab Waiter UC12: PlaceOrder UC13: MarkOrderReady UC14: EditMenu UC15: ViewStatistics UC16: AddEmployee UC17: RemoveEmployee Manager Cook Busboy

Figure F-1: The use case diagram for the restaurant automation project (Problem 2.7). UC16: AddEmployee Manager creates a profile for a new employee. The profile will contain information pertinent to that employee, such as employee name, telephone number, ID, salary and position. UC17: RemoveEmployee Manager deletes a profile of a former employee. The use case diagram is shown in Figure F-1. The auxiliary uses cases UC3 and UC4 for login/logout are included by other use case (except UC1 and UC2), but the lines are not drawn to avoid cluttering the diagram. There could also be a use case for the Manager to edit an existing employee profile when some of the parameters of an employee profile need to be changed. The reader should carefully trace the communications between the actors and the use cases and compare these with the brief description of the use cases, given above. I chose to include the database as part of the system because I feel that showing it as an external system (supporting actor), although true, would not contribute much to the informativeness of the diagram.

Problem 2.8: Traffic Information Solution

The use case diagram is shown in Figure F-2. UC1 ViewStatisticsAcrossArea and UC2 ViewStatisticsAlongPath directly ensue from the problem statement (described at the book website, given in Preface). Of course, the system cannot offer meaningful service before it collects sizeable amount of data to extract the statistics. It is sensible to assume that somebody (Administrator) should start the data collection process (UC3). The data collection must be run

Solutions to Selected Problems

373

Traffic Information System

UC2: ViewStatisticsAlongPath

User

participate

te initia init iate

UC1: ViewStatisticsAcrossArea

ipate partic te a rticip pa

Google Map

Database

initiate
Administrator

UC3: Start

partic

ipate

pate rtici pa

Yahoo! Traffic

UC4: CollectTrafficSample

initiate te it ia in

Timer / Cron Job Weather.com

UC5: CollectWeatherSample

participate

Figure F-2: The use case diagram for the traffic information project (Problem 2.8).

: System Timer / Cron Job

collect traffic sample loop [ for all zip codes ] read next zip code prepare request URL get traffic data (URL) process the response

Database

Yahoo! Traffic

opt

sample data is not duplicate store traffic sample delay before next query

re-set the cron-job timer

Figure F-3: System sequence diagram for the traffic data collection use case (Problem 2.8). periodically and that is the task of the Timer, which can be implemented as a Cron job (http://en.wikipedia.org/wiki/Cron)an automated process that operates at predefined time intervals and collects data samples (UC4 and UC5). As part of UC4, collecting the sample includes contacting the Yahoo! Traffic website to get the latest traffic updates for a given location. UC5 includes contacting the Weather.com website to read the current weather information. Also, in UC1 and UC2, the statistics are visualized on a geographic map retrieved from the Google Map website. The system may require login, particularly for the Administrator, but I chose not to show it because this is unessential to the problem at hand. There are two use cases related with data collection, UC4 and UC5. The system sequence diagram for UC4 is shown in Figure F-3. The Cron job can be designed to run both traffic and

Ivan Marsic

Rutgers University

374

weather data collection at the same time. The URL request is formed for each ZIP code in the given area. The traffic servers response must be processed to extract the traffic data; the data is stored only if it is new (not duplicate). A short delay (say 2 seconds) is inserted between two requests so that so that the traffic server does not mistake the large number of requests for a denial-of-service attack. Although the above design shows a single system, a better solution would be to design two completely independent systems: one for data collection and the other for user interaction (viewing traffic statistics). Their only interaction is via a common database which contains the collected data and traffic/weather records.

Problem 2.9: Patient Monitoring Solution

Problem 2.10: Home Access Using Face Recognition

The detailed description of AddUser for case (a), local implementation of face recognition, is as follows. (The use case RemoveUser is similar and left as an exercise.)

Use Case UC-6:

Initiating Actor: Actors Goal: Participating actors: Preconditions: Postconditions:

AddUser (sub-use case)

Landlord To register a new resident and record his/her demographic information. Tenant The Landlord is properly authenticated. The face recognition system trained on new residents face.

Related Requirements: REQ4 stated in Table 2-1

Main Success Scenario: 1. Landlord requests the system to create a new user record 2. System (a) creates a fresh user record, and (b) prompts for the values of the fields (the new residents name, address, telephone, etc.) 3. Landlord fills out the form with the tenants demographic information and signals completion 4. System (a) stores the values in the record fields, and (b) prompts for the Tenants password, which in this case is one or more images of the Tenants face 5. Tenant poses in front of the camera for a mug shot and signals for image capture 6. System (a) performs and affirms the image capture, (b) runs the recognition training algorithm until the new face is learned, (c) signals the training completion, and (d) signals that the new tenant is successfully added and the process is complete

Solutions to Selected Problems

375

For case (b), where face recognition is provided by a remote company, we need to distinguish a new actor, the FaceReco Company that provides authentication services. The detailed use case is as follows:

Use Case UC-6v2:

Initiating Actor: Actors Goal: Participating actors: Preconditions: Postconditions:

AddUser
Landlord To register a new resident and record his/her demographic information. Tenant, FaceReco The Landlord is properly authenticated. The face recognition system trained on new residents face.

Related Requirements: REQ4 stated in Table 2-1

Main Success Scenario: 1. Landlord requests the system to create a new user record 2. System (a) creates a fresh user record, and (b) prompts for the values of the fields (the new residents name, address, telephone, etc.) 3. Landlord fills the form with tenants demographic information and signals completion 4. System (a) stores the values in the record fields, and (b) prompts for the Tenants password, which in this case is one or more images of the Tenants face 5. Tenant poses in front of the camera for a mug shot and signals for image capture 6. System (a) performs the image capture, (b) sends the image(s) to FaceReco for training the face recognition algorithm, and (c) signals to the Landlord that the training is in progress 7. FaceReco (a) runs the recognition training algorithm until the new face is learned, and (b) signals the training completion to the System 8. System signals to the Landlord that the new tenant is successfully added and the process is complete Notice that above I assume that FaceReco will do training of their recognition system in real time and the Landlord and Tenant will wait until the process is completed. Alternatively, the training may be performed offline and the Landlord notified about the results, in which instance the use case ends at step 6.

Problem 2.11: Automatic Teller Machine Solution

Problem 2.12: Virtual Mitosis Lab Solution

The solution is shown in Figure F-4. The cell elements mentioned in the problem statement (described at the book website, given in Preface), directly lead to many concepts of the domain model: bead, centromere, nucleus, cell, guideline, etc. Two animations are mentioned in Figure 2 (see the problem statement at the book website), so these lead to the concepts of ProphaseAnimator and TelophaseAnimator. Also, the Builder concept is derived directly from the problem statement.

Ivan Marsic

Rutgers University

376

boundary NextButton pushes

1 Chromosome

uniformlyAlignedAlong Centromere 1 centeredAt 1 color position

*
Bead color position

Student
transitions starts boundary Instructions

color position displacement notifiesCompletion 1 .. 4 contains

Nucleus contains 1 visible 1

contains 2

Guideline position

displays control StateMachine tableOfStates currentState nextStageEnabled notifiesCompletion notifiesCompletion

1 Cell 1

makesVisible

Equator 1 makesInvisible 2

Spindle position length

contains contains

splitsInTwo

AutoBuilder

ManualBuilder

TelophaseAnimator

ProphaseAnimator

Figure F-4: The domain model for the cell division virtual laboratory (Problem 2.12). The concept which may not appear straightforward is the StateMachine. We may be tempted to show only the Next button, which is mentioned in the problem statement, as a concept. But, that does not tell us what is controlling the overall flow of the simulation. This is the task for the StateMachine, which keeps track of the current stage and knows when and how to transition to the next one. The nextStageEnabled attribute is set true when the StateMachine is notified of the current stage completion. This lets the user to proceed to the next stage of mitosis. Notice that some concepts, such as Centromere, Bead, and Nucleus, are marked as thing-type concepts, because they only contain data about position, color, and do not do any work. Conversely, the worker-type concepts, such as Chromosome and Cell exhibit behaviors. Given a non-zero displacement, the Chromosome has to bend according to the parabolic equation derived in the problem sttement at the book website (given in Preface). The Cell notifies the StateMachine when the user completes the required work. In terms of entity-boundary-control classification, StateMachine is a control object because it coordinates the work of other objects. NextButton and Instructions are boundary objects. All other objects are of entity type. Some attributes are not shown. For example, beads, centromere, nucleus, cell, guidelines, etc., also have the size dimension but this is not shown because it is not as important as other attributes. Also, some associations are omitted to avoid cluttering the diagram. E.g., the animators have to notify the StateMachine about the completion of the animation. Some concepts are related in more than one way. For example, Chromosome contains Beads and Centromere, but I chose not to show this. Instead, I show what I feel is more important, which is Beads are-uniformlyaligned-along Chromosome and Centromere is-centered-at Chromosome. These associations are

Solutions to Selected Problems

377

important to note because they highlight the geometric relationship of the chromosome and its elements. In anaphase, a yet-to-be specified concept has to make spindle fibers visible and centromeres displaceable. Also, the AutoBuilder manipulates all the cell components, and the ManualBuilder snaps the Beads into their final position. It is debatable whether the Guideline should be associated with the Nucleus or with the ManualBuilder, because unlike other concepts, which correspond to physical parts of the cell, the guidelines are an abstraction that only serves to help the user construct the cell. I have shown it associated with Nucleus. The notifications shown in the model are tentative and need to be reconsidered in the design phase. In the Build phase, it makes sense that each Chromosome notifies the Cell of its completion. The Cell, in turn, notifies the Builder when it has two Chromosomes completed, which finally notifies the StateMachine.

Problem 2.13 Solution

Problem 2.14: Fantasy Stock Investment Solution

(a) Based on the given use case BuyStocks we can gather the following doing (D) and knowing (K) responsibilities. The concept names are assigned in the rightmost column. Responsibility Description Typ Concept Name Coordinate actions of all concepts associated with a use case and delegate D Controller the work to other concepts. Players account contains the available fantasy money currently not K InvestmentAcct invested into stocks (called account balance). Other potential info includes Players historic performance and trading patterns. A record of all stocks that Player currently owns, along with the quantity K Portfolio of shares for each stock, latest stock price, current portfolio value, etc. Specification of the filtering criteria to narrow down the stocks for K QuerryCriteria querying their current prices. Examples properties of stocks include company name, industry sector, price range, etc. Fetch selected current stock prices by querying StockReportingWebsite. D StockRetriever HTML document returned by StockReportingWebsite, containing the K StockPricesDoc current stock prices and the number of available shares. Extract stock prices and other info from HTML doc StockPricesDoc. D StockExtractor Information about a traded stock, such as ticker symbol, trading price, etc. K StockInfo Prepare HTML documents to send to Players Web browser for display. D PageCreator E.g., create a page with stock prices retrieved from StockReportingWebsite HTML document that shows Player the current context, what actions can K InterfacePage be done, and outcomes of the previous actions/transactions. Info about a product, e.g., company name, product description, images, K Advertisement Information about advertising company; includes the current account info. K AdvertiserAcct Choose randomly next advertisement to be displayed in a new window. D AdvertisePoster Update revenue generated by posting the banner. Transaction form representing the order placed by Player, with stock K OrderForm

Ivan Marsic

Rutgers University

378

symbols and number of shares to buy/sell. Update players account and portfolio info after transactions and fees. Adjust the portfolio value based on real-world market movements. Log history of all trading transactions, including the details such as transaction type, time, date, player ID, stocks transacted, etc. Watch periodically real-world market movements for all the stocks owned by any player in the system. Track player performance and rank order the players for rewarding. Persistent information about player accounts, player portfolios, advertiser accounts, uploaded advertisements, revenue generated by advertisements, and history of all trading transactions. Information on the Fantasy Stock Investment Websites generated revenue, in actual monetary units, such as dollars.

D D D D K K

AcctHandler Logger MarketWatcher PerformTracker Database RevenueInfo

Although it is generally bad idea to mention specific technologies in the domain model, I breach this rule by explicitly mentioning HTML documents because I want to highlight that the system must be implemented as a Web application and HTML will remain the Web format for the foreseeable future. It may not be obvious that we need three concepts (StockRetriever, StockExtractor, PageCreator) to retrieve, extract, format, and display the stock prices. The reader may wonder why a single object could not carry out all of those. Or, perhaps two concepts would suffice? This decision is a matter of judgment and experience, and my choice is based on a belief that that the above distribution allocates labor roughly evenly across the objects. Also, the reader may notice that above I gathered more concepts than the use case BuyStocks alone can yield. Some concepts are generalized to cover both buying and selling transaction types. Other concepts, such as MarketWatcher, PerformTracker and RevenueInfo are deduced from the system description, rather than from the use case itself. Finally, the above table is only partial, because some obvious responsibilities, such as user authentication, are currently unassigned. Also, having the Portfolio concept alone is probably inadequate, because we may want to know details of each stock a Player owns. For this, we could re-use the StockInfo concept, so that Portfolio contains StockInfo. But this may be inadequate because StockInfo represents the current status of a stock on an exchange and the portfolio information may need a different representation. For example, we may want to know the price at which a stock was bought originally as well as its historic price fluctuations. Hence, a new concept should be introduced. Also, an additional concept may be introduced for Players contact and demographic information. (b) Attributes: Once the concepts are known, most of the attributes are relatively easy to identify. One attribute which may not be obvious immediately is the website address of the StockReportingWebsite. Let it be denoted as URL_StockRepSite and it naturally belongs to the StockRetriever concept. Associations:

Solutions to Selected Problems

379

boundary QueryCriteria selectedFilters

receives

control Controller

entity Portfolio ownedStocks portfolioValue updates entity AcctHandler control StockRetriever URL_StockRepSite entity AdvertisePoster retrieves asksForStockPrices updates

entity InvestmentAcct investorName accountBalance rewardBalance

posts

boundary InterfacePage receives

entity PageCreator

givesPages ToDisplay

boundary StockPricesDoc

asksForNewAd

receives

stocksToTrade

entity StockExtractor extracts entity StockInfo tickerSymbol sharePrice availableShares entity Logger

entity AdvertiserAcct companyName balanceDue contains

entity Advertisement

entity MarketWatcher

Figure F-5: The domain model for the fantasy stock investment website (Problem 2.14). It is left to the reader to identify and justify the associations. My version is shown in Figure F-5. One association that may be questionable at first is asks for stock prices between MarketWatcher and StockRetriever. The reason is that I assume that MarketWatcher will use the services of StockRetriever to obtain information about market movements, instead of duplicating this functionality. MarketWatcher only decides what stocks to watch (all owned by any of our investor players), how frequently, and then convey this information to AcctHandler to update the values of Portfolios. (c) The domain model is shown in Figure F-5. (d) Concept types are already labeled in Figure F-5. Advertisement could be argued as boundary, but I label it as entity, because this is actually the info stored in database, based on which the actual banner is generated. All concepts that appear on the boundary of the system, either between the system and the users browser or between the system and the stock reporting website are marked as boundary. So far we have two control concepts, and as we process more use cases, we may need to introduce dedicated Controllers for different uses cases. The remaining concepts are of entity type. It may not be readily apparent that StockRetriever should be a control type concept. First, this concept interacts with actors, in this case StockReportingWebsite, so it is another entry point into our system. The most important reason is that StockRetriever will be assigned many coordination activities, as will be seen later in the solution of Problem 2.17.

notifies

processes

boundary OrderForm

Ivan Marsic

Rutgers University

380

: GUI Customer enterCard() askPIN() enterPIN()

: Controller

: CustomerID

: IDChecker

: CustomerIDStore

: AcctInfo

: AcctManager : CashDispenserCtrl

enterCustomerID() id := create() acct := checkID(id) loop e := getNext() compare(id, e)

acct := create() alt askAmt() enterAmt() acct != null

askAmount()

enterAmount(amt) balance := withdraw(amt)

alt

balance >= 0

dispenseCash()

[else] [else] notifyInvalidID()

notifyID()

Figure F-6: The sequence diagram for the ATM, use case Withdraw Cash (Problem 2.15).

Problem 2.15: Automatic Teller Machine Solution

The solution is shown in Figure F-6.

Problem 2.16: Online Auction Site Solution

The solution is shown in Figure F-7. As already stated, in this simple version I assume that the items have no attribute indicating the auction expiration date. Although viewing bids before making decision is optional, I assume that this is a likely procedure. Before closing, Seller might want to review how active the bidding is, to decide whether to hold for some more time before closing the bid. If bidding is hot, it may be a good idea to wait a little longer.

Solutions to Selected Problems

381

: Controller Seller viewBids(itemName)

: ItemsCatalog

: ItemInfo

: BidsList

: Bid

: BuyerInfo Buyer

getItem(name) getBidsList() Before displaying bids, Controller could sort them in descending order.

display bids

closeAuction(itemName)

Seller decides to go with the highest current bid. getItem(name) setReserved(true) getBidsList()

loop Automatically select the highest current bid.

getNext() compare bid amounts

getBidder() getAddress() send email notification

Figure F-7: The sequence diagram for the online auction website, use case CloseAuction (Problem 2.16). The system loops through the bids and selects the highest automatically, rather than Seller having to do this manually. Notice that in this solution the system does not notify the other bidders who lost the auction; this may be added for completeness. The payment processing is part of a separate use case.

Problem 2.17: Fantasy Stock Investment Solution

(a) List of responsibilities: R1. Send the webpage received from StockReportingWebsite to StockExtractor for parsing R2. Send message to PageCreator to prepare a new webpage and insert the retrieved stock prices, the players account balance, and an advertisement banner R3. Send message to AdvertisePoster to select randomly an advertisement R4. Pass the webpage to Controller to send it to the players web browser for viewing

Ivan Marsic

Rutgers University

382

: StockRetriever receive (StockPricesDoc)

: StockExtractor

si : StockInfo

: PageCreator

: AdvertisePoster

: InvestmentAcct

: Controller

extractStocks() si := create() si page := preparePage(si) ad := selectAd() bal := getBalance() alt getInfo() bal >= 0 page := createTradingPage() page := createWarningPage() postPage(page)

Figure F-8: A sequence diagram for the fantasy stock investment website (Problem 2.17). Figure F-8 shows a feasible solution. Because StockRetriever is the first object to receive the stock prices from a third-party website, it naturally gets assigned R1. In this solution it also gets assigned R2 and R4, thus ending up performing most of the coordination work. Another option would be to assign R2 to StockExtractor by the principle of Expert Doer, because it first gets hold of StockInfo. However, High Cohesion principle argues against StockExtractor collaborating with PageCreator. Parsing HTML documents and extraction of stock information is sufficiently complex that StockExtractor should not be assigned other responsibilities. The diagram in Figure F-8 should be extended to consider exceptions, such as when the query to StockReportingWebsite is ill formatted, in which case it responds with an HTML document containing only an error message and no stock prices.

Problem 2.18 Solution

Problem 2.19: Patient Monitoring Solution

Problem 2.20 Solution

Problem 3.1 Solution

Solutions to Selected Problems

383

Problem 3.2 Solution

We can name the states as desired, but we must ensure that the entire state space is covered in our state diagram. The state space is shown in the figure (a). There are four different states, but there is only one type of the event: button-pushed. The corresponding UML state diagram is shown in the figure (b).
State space
Lit Bulb 2 Both bulbs unlit

State diagram
button-pushed Bulb1 lit Bulb2 unlit

button-pushed Unlit button-pushed Unlit Bulb 1 Lit Both bulbs lit

button-pushed

Bulb1 unlit Bulb2 lit

(a)

(b)

Problem 3.3 Solution

(a) List of states: Counting In this state, the auto-locking subsystem is counting down (or, up) for the duration of the timeout time. (We are assuming that the lock is currently open.) Stopped In this state, the auto-locking subsystem is idle waiting for the user to open the lock. (We are assuming that the lock is currently closed.) ArmingLock In this state, the auto-locking subsystem is arming the lock device. Initializing In this state, the auto-locking subsystem is initializing the timer for the requested duration of the timeout time. Paused In this state, the counting is suspended (it has not reached the threshold yet) either for a given period or indefinitely. (b) List of events: Paused resume Counter expired counter = 0 (if counting down), or: duration threshold (if counting up) pause Lock User requested arming the lock Unlock User requested disarming the lock Pause User requested pausing the countdown Resume User requested resuming the countdown Notice that for the remaining two transitions (Arming Stopped, and Initializing Counting) the transition is automatic (after the state activity is completed) and it is not caused
counter = 0 (if counting down) or: duration threshold (if counting up)

Counting

Arming Lock

lock

Initializing

Stopped

unlock

Ivan Marsic

Rutgers University

384

Next state Output Next

Input Completion notification

Build completed

Back

Build started
Build end-display Interphase started Build started Build start-display Interphase completed Build started Build start-display Interphase started Interphase start-display Prophase completed Prophase end-display Interphase started Interphase start-display

Build completed
Interphase start-display

Current state

Interphase started
Interphase end-display Prophase started

Interphase completed
Prophase start-display Prophase started

Prophase started
run ProphaseAnimator

Figure F-9. Partial state transition table for the mitosis virtual lab (Problem 3.4). The empty slots indicate that the input is ignored and the machine remains in the current state. by an event.

Problem 3.4: Virtual Mitosis Lab Solution

Initial part of the state transition table is shown in Figure F-9. The stages follow each other in linear progression and there is no branching, so it should be relatively easy to complete the table. The design is changed so that the Boolean attribute nextStageEnabled is abandoned in favor of splitting each mitosis stage into two states: stage-started and stage-completed. Notice that the domain model in Figure F-4 does not include a concept that would simulate the interphase stage. Because interphase does not include any animation and requires no users work, we can add a dummy object, which is run when interphase is entered and which immediately notifies the state machine that interphase is completed.
StateMachine # states : Hashtable # current : Integer # completed : boolean + next() : Object + complete() : Object + back() : Object

Part of the state diagram is shown in Figure F-10. I feel that it is easiest to implement the sub-states by toggling a Boolean variable, so instead of subdividing the stages into stage-started and stage-completed as in the table in Figure F-9, the class StateMachine would have the same number of states as there are stages of mitosis. The Boolean property completed, which corresponds to the nextStageEnabled attribute in Figure F-4, keeps track of whether the particular stage is completed allowing the user to proceed to the next stage. The class, shown at the right, has three methods: next(), complete(), and back(), which all return Object, which is the output issued when the machine transitions to the next state.

Solutions to Selected Problems

385

mitosis stage i 1 next / next / warning show start-display completed = false

mitosis stage i next / show start-display completed = true

mitosis stage i + 1

complete / show end-display

completed = true

completed = true

back / show start-display

back / show start-display

Figure F-10. Partial state diagram for the mitosis virtual lab (Problem 3.4).

Problem 3.5 Solution

Problem 3.6 Solution

Ivan Marsic

Rutgers University

386

: ElevatorMain start loop

: InfoPanel

: CarControl

dcf : DoorControl

obf : OutButton

ibf : InButton

readFloorSensors() readButtons()

opt

car arrived at floor f arrivedAt(f : int) adjustDisplay() illuminate() illuminate() stopAt(f : int)

setIlluminate(false) setIlluminate( false)

stopMotor()

operateDoors()

openDoors()

{30 sec.}

closeDoors()

startMotor()

opt

car departed

opt

button(s) pushed

Figure F-11. Partial interaction diagram for the elevator problem (Problem 3.7).

Problem 3.7: Elevator Control Solution

Part of the interaction diagram is shown in Figure F-11. The UML diagram shows only the interaction sequence for the case when the elevator car arrives at floor f. The other two cases, when the car departs from the current floor and when a physical button is pushed are left to the reader as exercise. Notice that we do use several opt choices rather than an alt choice, because the events (car-arrived, car-departed, button pushed) are not mutual alternatives. Although car-arrived and car-departed cannot happen at the same time, they should not be represented with an alt. Because it may be that neither one of them happened, it is not appropriate to show them as: IF (car-arrived) THEN do-actions-when-car-arrived ELSE do-actions-when-car-departed (Note: Compare this solution to that of Problem 5-6.)

Solutions to Selected Problems

387

Problem 3.8: OCL Contract for Auction Website Solution

First, we need to add one attribute and one operation to the original class diagram, to make the solution easier. We will add an attribute heldBy : BuyerInfo on the class ItemInfo, which refers to the person to whose name the item is currently reserved (if any). To access this attribute, we add operation getHeldBy() : BuyerInfo on the same class. Finally, we will also need to check for the highest bidder. Unlike old-fashioned auctions where all participants are in the same room, we cannot assume that the highest bid will arrive last. The order of bid arrivals will depend on the time an order is placed as well as on network delays. Therefore, bids must be explicitly ordered. There is an interesting side issue of how and when the class BidsList determines the highest bidder. One option is to introduce an operation getHighestBidder() : BuyerInfo and do sorting every time this operation is invoked. Another option is to sort the bids every time a new bid is added, in which case the highest bid is accessed as the first item (head) of the list. The reader may wish to consider which solution is more efficient. Here, we will opt for the latter solution, and so the link between BidsList and Bid in the original class diagram needs the label {ordered} near the Bid class symbol, indicating that the list of bids is ordered (from highest to lowest). We will assume that an item in the catalog is either available for bidding (then its auction is open), or reserved (then its auction is temporarily closed, until the payment is processed). If the highest bidder reneges and abandons the bid, then the item again becomes available. Otherwise, if the payment is successful, the item is removed from the catalog. Therefore, for the preconditions, all we need to check is that the item is not reserved: context Controller::closeAuction(itemName) pre: !self.findItem(itemName).isReserved() As for postconditions, we have to ensure that (1) the item is reserved and (2) under the name of the highest bidder (given that there was at least one bidder): context Controller::closeAuction(itemName) post: findItem(itemName).isReserved()

context Controller::closeAuction(itemName) post: if not findItem(itemName).getBidsList()->isEmpty() then findItem(itemName).getHeldBy().getName().equals( findItem(itemName).getBidsList()->first(). getName()@pre ) Notice that all of the above operations return a single object, except for getBidsList() which returns a collection. In the latter case, we use the arrow symbol ->. Recall that BidsList

Ivan Marsic

Rutgers University

388

maintains an {ordered} list of Bids, so the returned collection is a sequence, and the highest bidder is accessed as the first item of the sequence.

Problem 3.9 Solution

Problem 4.1 Solution

Problem 4.2 Solution

Problem 4.3 Solution

(a) The solution is shown in Figure F-12. (b) The solution is shown in Figure F-13. (c) The cyclomatic complexity can be determined simply by counting the total number of closed regions, as indicated in Figure F-13. Notice in Figure F-13 (a) how nodes n4 and n5, which call subroutines, are split into two nodes each: one representing the outgoing call and the other representing the return of control. The resulting nodes are connected to the beginning/end of the called subroutine, which in our case is Quicksort itself.

Solutions to Selected Problems

389

Partition: Quicksort:
Start

Start x A[r] xp1 jp

YES Call Partition

p<r

NO YES YES NO

jr1

NO

Call Quicksort Call Quicksort

A[j] x

ii+1 Exchange A[i] A[j] End jj+1 Exchange A[i+1] A[r]

(a)

(b)

End

Figure F-12: Flowchart of the Quicksort algorithm (Problem 4.3).

In Section 4.x.y we encountered two slightly different formulas for calculating cyclomatic complexity V(G) of a graph G. Using the original formula by McCabe [1974] in the case of Figure F-13, we have V(G) = 22 19 + 22 = 7 Notice that there are a total of 19 nodes in Quicksort and Partition because nodes n4 and n5 are each split in two. Alternatively, [Henderson-Sellers & Tegarden, 1994] linearly-independent cyclomatic complexity for the graph in Figure F-13 yields VLI(G) = 22 19 + 2 + 1 = 6 which is what we obtain, as well, by a simple rule: VLI(G) = number of closed regions + 1 = 5 + 1 = 6 (Closed regions are labeled in Figure F-13.)

Ivan Marsic

Rutgers University

390

Partition: Quicksort:
n1 n1

n7 e11 n8 e12 n9 e13

n10

R1
n2 e7 e5 e2 n3 n3 n2

e1

e3

e14
n11

R4
e4 n4 n4 e21 e9 e17
n13 n12

e15 e18

e16

R2
n4 e6

e19
n14

R5

n5 n5 n5 e8 n6 e10

e20
n15 n16

R3

n6
n17

e22

(a)

(b)

Figure F-13: Graph of the Quicksort algorithm. Nodes n4 and n5 in (a) are split in two nodes each, and these nodes are connected to the called subroutine, which in this case is Quicksort itself. If Partition subroutine remains separate, the total number of closed regions is 5.

Problem 4.4 Solution

Problem 5.1 Solution

Problem 5.2 Solution

Seller may want to be notified about the new bids; Buyer may want to be notified about closing the auction for the item that he/she bid for. Therefore, good choices for implementing the Subscriber interface are SellerInfo and BuyerInfo. Conversely, good choices for implementing the Publisher interface are ItemInfo and BidsList. ItemInfo publishes the event when the flag reserved becomes true. All the BuyerInfo objects in the bidders list receive this event and send email notification to the respective bidders. Conversely, BidsList publishes the event when a new Bid object is added to the list. The SellerInfo object receives the event and sends email notification to the respective seller.

Solutions to Selected Problems

391

Event Item becomes reserved (its auction is closed) New Bid added to an items list of bids

Publisher ItemInfo BidsList

Subscriber BuyerInfo SellerInfo

Problem 5.3: Patient Monitoring Solution

Problem 5.4 Solution

Problem 5.5 Solution

Problem 5.6: Elevator Control Solution

3 To solve this problem, it is useful to consider the interaction diagram for the system before the publisher-subscriber pattern is introduced, which is given in the solution of Problem 3.7 (Figure F-11). From the figure, we can see that ElevatorMain is suitable as a Publisher-type class, and InformationPanel, CarControl, OutsideButton, and InsideButton are suitable as Subscriber-type classes. Notice that InformationPanel and CarControl need to know the floor at which the elevator car arrived, which they obtain through arrivedAt(floorNum : int). In contract, for OutsideButton and InsideButton, the caller knows which floor is represented by which button and correspondingly calls arrived()only on the appropriate objects. We could try having a single event corresponding to the elevator car arrival at a floor, but there is a slight problem. Because the Publisher should be agnostic about its Subscribers and should notify indiscriminately all Subscribers subscribed for a particular event type, we will have the Publisher unnecessarily call the objects corresponding to the buttons other than the ones where the elevator car arrived. The only way that I can think of to avoid this is to introduce n events corresponding to the car arrival to floor i, where 1 i n and n is the total number of floors. This does not appear as a more elegant solution, so we stay with the solution where all button objects will be notified of the elevator car arrival to floor i, but only the appropriate objects will turn off the button illumination.
14 13 12 11 10 8 6 4 1 L 9 7 5 3 2 B

P1 P2

Ivan Marsic

Rutgers University

392

: ElevatorMain start loop

: InfoPanel

: CarControl

dcf : DoorControl

obf : OutButton

ibf : InButton

readFloorSensors() readButtons()

opt

car arrived at floor f arrivedAt(f : int) adjustDisplay() arrivedAt(f : int) arrivedAt(f : int) arrivedAt(f : int)

setIlluminate(false) setIlluminate( false)

stopMotor()

operateDoors()

openDoors()

{30 sec.}

closeDoors()

startMotor()

opt

car departed

opt

button(s) pushed

Figure F-14. Partial interaction diagram for the elevator problem (Problem 5.6). The interaction diagram is shown in Figure F-14. Notice that this diagram is almost identical to the one in Figure F-11, except for the operation names. The reader should remind themselves of advantages of the Publish-Subscribed design pattern described in Section 5.1. In summary, the Publisher will generate three types of events: arrivedAt(floorNum : int) informs a Subscriber that the elevator car arrived at floor floorNum. departed()informs a Subscriber that the car has departed from the current floor. pressed(floorNum : int) informs a Subscriber that the physical button associated with floor floorNum was pressed. At first, it may appear that the DoorControl class is also a subscriber for arrivedAt() events. However, it is not for the following reason. First, the door should be opened only when the elevator car stopped moving. According to the problem description, the arrivedAt() event will occur when the elevator car is within 10 cm of the rest position at the floor. That is, it

Solutions to Selected Problems

393

may still be moving. As shown in Figure F-14, the class CarControl stops the motor, and only when this is done, DoorControl should be asked to open the doors. Acknowledging this fact, one may still try to implement the communication between CarControl and DoorControl using the publish/subscribe mechanism. A potential solution is shown in this figure: I hope that the reader can appreciate that this would be a much less elegant solution than the one in Figure F-14. In addition, CarControl and DoorControl would be the only publishers/subscribers for each other, so there is no benefit of using the publish/subscribe mechanism in this case.

: CarControl

dcf : DoorControl

subscribe for motor stopped

subscribe for door closed

arrivedAt(f : int)

stopMotor() motorStopped() openDoors()

closeDoors() doorsClosed() startMotor()

The above solution is appropriate for a singlethreaded case and I cannot think of another way to assign publisher and subscriber roles in a single-threaded case. In case where multiple threads are implemented, the solution might look quite different. One issue that may be particularly confusing is whether OutsideButton and InsideButton objects should actually be considered as Publishers, rather than Subscribers. In the current scenario where the system is single threaded, it would be meaningless to have OutsideButton and InsideButton objects as Publishers, because they would anyway be called from the main loop (ElevatorMain) just to read the physical button status and pass it to other objects. This would not be considered a design improvement. However, if we had a different scenario, with multiple threads and if each OutsideButton and InsideButton object were to run in its own thread, then it would make sense to have them as Publishers, because they would directly read information from their associated physical buttons. I have not considered carefully the merits of a multithreaded solution, but I have some concerns. Depending on the number of floors and elevators, there could potentially be a large number of threads required if each button were to run in a separate thread. This may appear as a conceptually more elegant solution, but may result in a logistic nightmare of managing so many threads. And the overall gain compared to a single-threaded solution might not be that great. My intuition for a multi-threaded solution would be to have three threads only, one to read the floor sensors and publish this information to other objects, another to read all the physical buttons (inside and outside ones) and publish this information to other objects, and the third thread to do everything else.

Problem 5.7 Solution

Ivan Marsic

Rutgers University

394

Problem 5.8 Solution

(a) Substituting the yield() method call for wait() is correct but not efficientthis is so called a busy-wait spin loop, which wastes an unbounded amount of CPU time spinning uselessly. On the other hand, wait-based version rechecks conditions only when some other thread provides notification that the objects state has changed. (b) This is not correct. When an action is resumed, the waiting thread does not know if the condition is actually met; it only knows that it has been woken up. Also, there may be several threads waiting for the same condition, and only one will be able to proceed. So it must check again. Check the reference [Sandn, 2004] for details.

Problem 5.9 Solution

Parking lot occupancy monitoring. I will show two different UML diagrams for the two threads. The treads execute independently, and the only place they interact is when the shared object is locked/unlocked or in coordination using wait() / notify(). If a thread finds the shared object already locked, it is blocked and waiting until the lock is released. The lock transfer is performed by the underlying operating system, so it is not the application developers responsibility.

Solutions to Selected Problems

395

: EnterThread Car requestEntry() loop lock() full := isFull() full == false carEntered()

: SharedState

: ExitThread Car

alt

occupancy++

opt

occupancy == capacity signal: parking full"

unlock() issue ticket & lift entrance pole [else]

transfer lock

wait()

transfer lock

Figure F-15. Enter thread of the parking lot system, Problem 5.9. The UML diagram for the EnterThread is shown in Error! Reference source not found.. Notice that the thread first grabs the shared state, updates it, and releases it. Only then is the ticket issued and the pole is lifted. This is so that the other thread (ExitThread) does not need to wait too long to access the shared state, if needed. If the occupancy becomes equal to capacity, the shared object will post the signal parking full, e.g., it will turn on the red light. No new cars will be allowed into the lot. In this case the method isFull() on SharedState returns true. If the lot is already full, the thread calls wait() and gets suspended until the other thread calls notify(). Conversely, the UML diagram for the ExitThread is shown in Figure F-16. The two threads, as designed above, can interact safely and the two diagrams can be connected at any point.

Ivan Marsic

Rutgers University

396

: EnterThread Car

: SharedState

: ExitThread Car

requestExit() lock() carExited() occupancy

opt

occupancy == capacity 1 remove signal parking full"

notify() transfer lock unlock() process payment & lift exit pole

Figure F-16. Exit thread of the parking lot system, Problem 5.9.

Problem 5.10 Solution

Problem 5.11 Solution

Problem 5.12 Solution

Problem 5.13 Solution

Distributed Publisher-Subscriber design pattern using Java RMI.

Problem 5.14 Solution

Security for an online grocery store. The key pairs used for secure communication in our system are shown in Figure F-17. Due to the stated requirements, all information exchanges must be confidential.

Solutions to Selected Problems

397

Customer
enter selection (items catalog)
+ KM

Merchant

Bank

place order (selected items")

KM

KC + KB

enter credit card info (payment amount)

+ KC

process payment (card info")

+ KB

approve transaction (card info, payment amount")

KB + KM

KM KC

notify outcome (result value)

+ KC

notify outcome (result value)

Figure F-17. Key pairs needed for secure communication. See text for explanation.

(a) There must be at least three public-private key pairs issued: + (i) Merchants pair: ( K M , K M ) + (ii) Customers pair: ( K C , K C ) + (iii) Banks pair: ( K B , K B ) Recall that every receiver must have his/her own private key and the corresponding public key can be disclosed to multiple senders. Because every actor at some point receives information, they all must be given their own key pair.

(b) I assume that each actor generates his/her own key pair, that is, there is no special agency dedicated for this purpose.
+ The Merchant issues its pair and sends K M to both the Bank and Customer. It is reasonable to + send K M only once to the Bank for the lifetime of the key pair, because it can be expected that

the Merchant and Bank will have regular message exchanges. Conversely, it is reasonable to send + K M to the customer once per shopping session, because the shopping sessions can be expected to be very rare events.

Ivan Marsic

Rutgers University

398

+ The Customer issues his/her pair and sends K C to the Merchant only. Because shopping session + likely is a rare event, K C should be sent at the start of every shopping session. + The Bank sends its public key K B to the Merchant, who keeps a copy and forwards a copy to the + Customer. K B will be sent to the Merchant once for the lifetime of the key pair, but the Merchant

will forward it to the Customer every time the Customer is prompted for the credit card information.

(c) As shown in Figure F-17, every actor keeps their own private key K i secret. Both the Bank and
+ + Customer will have the Merchants public key K M . Only the Merchant will have K C , and both + the Merchant and customer will have K B .

(d) The key uses in encryption/decryption are shown in Figure F-17. A public key K i+ is used for encryption and a private key K i is used for decryption. There is an interesting observation to make about the transaction authorization procedure. Here, + the Customer encrypts their credit card information using K B and sends to the Merchant who
cannot read it (because it does not have K B ). The Merchant needs to supply the information

about the payment amount, which can be appended to the Customers message or sent in a separate message. It may be tempting to suggest that the Customer encrypts both their credit card information and the payment amount, and the Merchant just relays this message. However, they payment amount information must be encrypted by the Merchant, because the Customer may spoof this information and submit smaller than the actual amount. The actual process in reality is more complex, because there are many more actors involved and they rarely operate as their own key-makers. The interested reader should consult [Ford & Baum, 2001]. A summary of the SET (Secure Electronic Transaction) system for ensuring the security of financial transactions on the Internet can be found online at http://mall.jaring.my/faqs.html#set.

Problem 5.15 Solution

Problem 6.1 Solution

Solutions to Selected Problems

399

Problem 6.2 Solution

What we got in Listing 6-13 is equivalent to Listing 6-1; what we need to get should be equivalent to Listing 6-7. For the sake of simplicity, I will assume that all elements that are left unspecified are either arbitrary strings of characters (class name and semester) or integers (class index and enrollment). Otherwise, the listing below would be much longer if I tried to model them realistically, as well. Listing Sol-1: XML Schema for class rosters.
1 <?xml version="1.0" encoding="UTF-8"?> 2 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 3 targetNamespace="http://any.website.net/classRoster" 4 xmlns="http://any.website.net/classRoster" 5 elementFormDefault="qualified"> 6 7 <xsd:element name="class-roster"> 8 <xsd:complexType> 9 <xsd:sequence> 10 <xsd:element name="class-name" type="xsd:string"/> 11 <xsd:element name="index" type="xsd:integer"/> 12 <xsd:element name="semester" type="xsd:string"/> 13 <xsd:element name="enrollment" type="xsd:integer"/> 14 <xsd:element ref="student" 14a minOccurs="0" maxOccurs="unbounded"> 15 </xsd:sequence> 16 </xsd:complexType> 17 </xsd:element> 18 19 <xsd:element name="student"> 20 <xsd:complexType> 21 <xsd:sequence> 22 <xsd:element name="student-id"> 23 <xsd:simpleType> 24 <xsd:restriction base="xsd:string"> 25 <xsd:pattern value="\d{3}00\d{4}"/> 26 </xsd:restriction> 27 </xsd:simpleType> 28 </xsd:element> 29 30 <xsd:element name="name"> 31 <xsd:complexType> 32 <xsd:sequence> 33 <xsd:element name="first-name" type="xsd:string"/> 34 <xsd:element name="last-name" type="xsd:string"/> 35 </xsd:sequence> 36 </xsd:complexType> 37 </xsd:element> 38 39 <xsd:element name="school-number"> 40 <xsd:simpleType> 41 <xsd:restriction base="xsd:string"> 42 <xsd:pattern value="\d{2}"/> 43 </xsd:restriction> 44 </xsd:simpleType> 45 </xsd:element> 46

Ivan Marsic

Rutgers University

400

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73

<xsd:element name="graduation" type="xsd:gYear"/> <xsd:element name="grade" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="A"/> <xsd:enumeration value="B+"/> <xsd:enumeration value="B"/> <xsd:enumeration value="C+"/> <xsd:enumeration value="C"/> <xsd:enumeration value="D"/> <xsd:enumeration value="F"/> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> <xsd:attribute name="status" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="full-time"/> <xsd:enumeration value="part-time"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType> </xsd:element> </xsd:schema>

Problem 6.3 Solution

References

1. 2.

A. J. Albrecht, Measuring application development productivity, Procedings of the IBM Applications Development Symposium, pp. 83, Monterey, CA, October 1979. B. A. Allan, R. C. Armstrong, A. P. Wolfe, J. Ray, D. E. Bernholdt, and J. A. Kohl, The CCA core specification in a distributed memory SPMD framework, Concurrency and Computation: Practice and Experience, vol. 14, pp. 323-345, 2002. E. B. Allen, and T. M. Khoshgoftaar, Measuring coupling and cohesion: An information-theory approach, Proceedings of the Sixth IEEE International Software Metrics Symposium, pp. 119-127, November 1999. E. Armstrong, J. Ball, S. Bodoff, D. Bode Carson, I. Evans, D. Green, K. Haase, and E. Jendrock, The J2EE 1.4 Tutorial: For Sun Java System Application Server Platform Edition 8.2, Sun Microsystems, Inc., December 5, 2005. Online at: http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html R. M. Baecker, Sorting out sorting: A case study of software visualization for teaching computer science, in Stasko, J., Domingue, J., Brown, M., and Price, B. (Editors), Software Visualization: Programming as a Multimedia Experience, pp. 369-381, The MIT Press, Cambridge, MA, 1998. Online at: http://kmdi.utoronto.ca/rmb/papers/B7.pdf C. H. Bennett, On the nature and origin of complexity in discrete, homogeneous, locally-interacting systems, Foundations of Physics, vol. 16, pp. 585-592, 1986. C. H. Bennett, Information, dissipation, and the definition of organization, in D. Pines (Editor), Emerging Syntheses in Science, Addison-Wesley, Reading, MA, 1987. C. H. Bennett, How to define complexity in physics, and why, in W. H. Zurek (Editor), Complexity, Entropy, and the Physics of Information, SFI Studies in the Science of Complexity, vol. VIII, pp. 137-148, Addison-Wesley, Redwood City, CA, 1990. I. Ben-Shaul, O. Holder, and B. Lavva, Dynamic adaptation and deployment of distributed components in Hadas, IEEE Transactions on Software Engineering, vol. 27, no. 9, pp. 769-787, September 2001. pp.89-93, May 1999. Online at: http://www.sciam.com/article.cfm?articleID=0008C786-91DB-1CD6B4A8809EC588EEDF&catID=2

3.

4.

5.

6. 7. 8.

9.

10. J. Bosak and T. Bray, XML and the second-generation Web, Scientific American,

11. R. Bramley, K. Chiu, S. Diwan, D. Gannon, M. Govindaraju, N. Mukhi, B. Temko, and

M. Yechuri, A component based services architecture for building distributed

401

Ivan Marsic

Rutgers University

402

applications, Proceedings of the Ninth IEEE International Symposium on High Performance Distributed Computing (HPDC'00), pp. 51-, Pittsburgh, PA, August 2000.
12. L. C. Briand, J. W. Daly, and J. K. Wst, A unified framework for coupling

measurement in object-oriented systems, IEEE Transactions on Software Engineering, vol. 25, no. 1, pp. 91-121, January 1999.
13. L. C. Briand, S. Morasca, and V. R. Basili, Property-based software engineering

measurement, IEEE Transactions on Software Engineering, vol. 22, no. 1, pp. 68-85, January 1996.
14. F. P. Brooks, The Mythical Man-Month: Essays on Software Engineering, 20th

Anniversary Edition, Addison-Wesley Inc., Reading, MA, 1995.

15. M. Broy, A. Deimel, J. Henn, K. Koskimies, F. Plil, G. Pomberger, W. Pree, M. Stal,

and C. Szyperski, What characterizes a (software) component?, Software Concepts & Tools, vol. 19, pp. 49-56, 1998.
16. F. Buschmann, R. Meunier, H. Rohnert, P. Sommerlad, and M. Stal, Pattern-Oriented

Software Architecture: A System of Patterns, John Wiley & Sons, Inc., New York, 1996.
17. K. L. Calvert and M. J. Donahoo, TCP/IP Sockets in Java: Practical Guide for

Programmers, Morgan Kaufmann Publishers, San Francisco, CA, 2002.

18. D. Caromel and J. Vayssire, A security framework for reflective Java applications,

SoftwarePractice & Experience (John Wiley & Sons, Inc.), vol. 33, no. 9, 821-846, July 2003.
19. E. R. Carroll, Estimating software based on use case points, Proceedings of the 2005

ACM Conference on Object-Oriented, Programming, Systems, Languages, and Applications (OOPSLA '05), pp. 257-265, San Diego, CA, October 2005.
20. R. Chellappa, P. J. Phillips, and D. Reynolds (Editors), Special Issue on Biometrics:

Algorithms and Applications of Fingerprint, Iris, Face, Gait, and Multimodal Recognition, Proceedings of the IEEE, vol. 94, no. 11, November 2006.
21. G. Chen and B. K. Szymanski, Object-oriented paradigm: Component-oriented

simulation architecture: Toward interoperability and interchangeability, Proceedings of the 2001 Winter Simulation Conference (WSC 2001), pp. 495-501, Arlington, VA, December 2001.
22. M. Cohn, Agile Estimating and Planning, Prentice-Hall PTR, Upper Saddle River, NJ,

2006.
23. M. Cohn, Estimating with use case points, Methods & Tools, vol. 13, no. 3, pp. 3-13,

Fall 2005. Online at: http://www.methodsandtools.com/archive/archive.php?id=25

24. M. Cohn, User Stories Applied: For Agile Software Development, Addison-Wesley,

Boston, MA, 2004.

25. D. Coleman, P. Arnold, S. Bodoff, C. Dollin, H. Gilchrist, F. Hayes, and P. Jeremaes,

Object-Oriented Development: The Fusion Method, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1994.

References

403

26. L. L. Constantine and L. A. D. Lockwood, Software for Use: A Practical Guide to the

Models and Methods of Usage-Centered Design, Addison-Wesley Professional / ACM Press, Reading, MA, 1999.
27. L. L. Constantine, G. J. Myers, and W. P. Stevens, Structured design, IBM Systems

Journal, vol. 13, no. 2, pp. 115-139, May 1974.

28. K. Cusing, Why projects fail, Computer Weekly, November 21, 2002. 29. M. A. Cusumano, The changing software business: Moving from products to services,

IEEE Computer, vol. 41, no. 1, pp. 20-27, January 2008.

30. G. Cybenko and B. Brewington, The foundations of information push and pull, In D.

OLeary (Editor), Mathematics of Information, Springer-Verlag, 1998. Online at: http://actcomm.dartmouth.edu/papers/cybenko:push.pdf

31. R. Davies and F. Pfenning, A modal analysis of staged computation, Journal of the

ACM (JACM), vol. 48, no. 3, pp. 555-604, May 2001.

32. A. Denning, Active X Controls Inside Out, Second Edition, Microsoft Press, Redmond,

Washington, 1997.
33. M. J. Donahoo and K. L. Calvert, Pocket Guide to TCP/IP Sockets (C Version), Morgan

Kaufmann Publishers, San Francisco, CA, 2001.

34. P. Dourish, Using metalevel techniques in a flexible toolkit for CSCW applications,

ACM Transactions on Computer-Human Interaction (TOCHI), vol. 5, no. 2, pp.109-155, June 1998.
35. B. Eckel, Thinking in Java, Third Edition, Prentice Hall PTR, Upper Saddle River, NJ,

2003. Online at: http://www.mindview.net/Books

36. The Economist, Security through viral propagation, The Economist, pp. 7-8 of the

special section: Technology Quarterly, December 4, 2004. Online at: http://www.economist.com./science/tq/displayStory.cfm?story_id=3423046

37. J. Eder, G. Kappel, and M. Schrefl, Coupling and cohesion in object-oriented systems,

Proceedings of the Conference on Information and Knowledge Management, Baltimore, MA, 1992.
38. P. Th. Eugster, P. A. Felber, R. Guerraoui, and A.-M. Kermarrec, The many faces of

publish/subscribe, ACM Computing Surveys, vol. 35, no. 2, pp. 114-131, June 2003.
39. M. E. Fayad and D. C. Schmidt, Object-oriented application frameworks,

Communications of the ACM, vol. 40, no. 10, pp. 32-38, October 1997.
40. N. E. Fenton and S. L. Pfleeger, Software Metrics: A Rigorous and Practical Approach,

Second Edition (Revised Printing), PWS Publishing Company (International Thomson Publishing), Boston, MA, 1998.
41. R. P. Feynman, R. W. Allen, and T. Hey, Feynman Lectures on Computation, Perseus

Publishing, 2000.

Ivan Marsic

Rutgers University

404

42. W. Ford and M. S. Baum, Secure Electronic Commerce: Building the Infrastructure for

Digital Signatures and Encryption, Second Edition, Prentice Hall PTR, Upper Saddle River, NJ, 2001.
43. M. Fowler, UML Distilled: A Brief Guide to the Standard Object Modeling Language,

Third Edition, Addison-Wesley, Inc., Reading, MA, 2004.

44. E. Gamma, R. Helm, R. Johnson, and J. Vlissides. Design Patterns: Elements of

Reusable Object-Oriented Software, Addison Wesley Longman, Inc., Reading, MA, 1995. The pattern descriptions are available online, e.g., http://www.dofactory.com/Patterns/Patterns.aspx
45. M. Gell-Mann and C. Tsallis (Editors), Nonextensive Entropy: Interdisciplinary

Application, Oxford University Press, 2004.

46. M. Gladwell, The Tipping Point: How Little Things Can Make a Big Difference, Back

Bay Books / Little, Brown and Co., New York, NY, 2000.
47. E. G. Goodaire and M. M. Parmenter, Discrete Mathematics with Graph Theory, Third

Edition, Pearson Prentice Hall, Upper Saddle River, NJ, 2006.

48. S. D. Guttenplan, The Languages of Logic: An Introduction to Formal Logic, Basil

Blackwell, 1986.
49. M. H. Halstead, Elements of Software Science, Elsevier North-Holland, New York, NY,

1977.
50. R. Harrison, S. J. Counsell, and R. V. Nithi, An evaluation of the MOOD set of object-

oriented software metrics, IEEE Transactions on Software Engineering, vol. 24, no. 6, pp. 491-496, June 1998.
51. A. Helal, W. Mann, H. Elzabadani, J. King, Y. Kaddourah, and E. Jansen, Gator Tech

smart house: A programmable pervasive space, IEEE Computer, vol. 38, no. 3, pp 6474, March 2005.
52. B. Henderson-Sellers, Object-Oriented Metrics: Measures of Complexity, Prentice-Hall

Inc., Upper Saddle River, NJ, 1996.

53. B. Henderson-Sellers, L. L. Constantine, and I. M. Graham, Coupling and cohesion:

Towards a valid suite of object-oriented metrics, Object-Oriented Systems, vol. 3, no. 3, 143-158, 1996.
54. B. Henderson-Sellers and D. Tegarden, The theoretical extension of two versions of

cyclomatic complexity to multiple entry/exit modules, Software Quality Journal, vol. 3, no. 4, pp. 253-269, December 1994.
55. M. Henning, The rise and fall of CORBA, ACM Queue, vol. 4, no. 5, pp. 28-34, June

2006. Online at: http://acmqueue.com/rd.php?c.396

56. J. Henry and D. Gotterbarn, Coupling and cohesion in object-oriented design and

coding, Proceedings of the 1996 ACM 24th Annual Conference on Computer Science, pp. 149, Philadelphia, PA, 1996.

References

405

57. J. C. Hou et al., J-Sim: Component-Based, Compositional Simulation Environment.

Online at: http://www.j-sim.org/

58. M. E. C. Hull, P. N. Nicholl, P. Houston, and N. Rooney, Towards a visual approach

for component-based software development, Software Concepts & Tools, vol. 19, pp. 154-160, 2000.
59. D. Ince, Software Development: Fashioning the Baroque, Oxford University Press,

Oxford, UK, 1988.

60. M. Jackson, Software Requirements and Specifications: A Lexicon of Practice,

Principles and Prejudices, Addison-Wesley Professional, Reading, MA, 1995.

61. M. Jackson, Problem Frames: Analyzing and Structuring Software Development

Problems, Addison-Wesley Professional, Reading, MA, 2001.

62. I. Jacobson, G. Booch, and J. Rumbaugh, The Unified Software Development Process,

Addison-Wesley, Reading, MA, 1999.

63. M. Johnson, The trick to controlling bean customization. JavaWorld, November 1997.

Online at: http://www.javaworld.com/javaworld/jw-11-1997/jw-11-beans.html

64. C. Jones, Patterns of large software systems: Failure and success, IEEE Computer,

vol. 28, no. 3, pp. 86-87, 1995.

65. R. Kanigel, The One Best Way: Frederick Winslow Taylor and the Enigma of Efficiency,

The MIT Press, Cambridge, MA, 2005.

66. G. Karner, Metrics for Objectory, Diploma Thesis, University of Linkping, Sweden,

No. LiTH-IDA-Ex-9344:21. December 1993.

67. C. Kelleher and R. Pausch, Lowering the barriers to programming: A taxonomy of

programming environments and languages for novice programmers, ACM Computing Surveys, vol. 37, no. 2, pp. 83-137, June 2005.
68. B. Kirwan and L. K. Ainsworth (Editors), A Guide to Task Analysis, CRC Press (Taylor

& Francis, Ltd.), Atlanta, GA, 1992.

69. B. A. Kitchenham, S. L. Pfleeger, and N. E. Fenton, Towards a framework for software

measurement validation, IEEE Transactions on Software Engineering, vol. 21, no. 12, pp. 929-944, December 1995.
70. G. Krasner and S. Pope, A cookbook for using the model-view-controller user interface

paradigm in Smalltalk-80, Journal of Object-Oriented Programming, vol. 1, no. 3, pp. 26-49, August/September 1988.
71. B. Krishnamurthy and J. Rexford, Web Protocols and Practice: HTTP/1.1, Networking

Protocols, Caching, and Traffic Measurement, Addison-Wesley, Inc., Reading, MA, 2001.
72. S. Kusumoto, F. Matukawa, K. Inoue, S. Hanabusa, and Y. Maegawa, Estimating effort

by use case points: Method, tool and case study, Proceedings of the IEEE 10th International Symposium on Software Metrics (METRICS04), pp. 292-299, September 2004.

Ivan Marsic

Rutgers University

406

73. A. van Lamsweerde, Requirements Engineering: From System Goals to UML Models to

Software Specifications, John Wiley & Sons, Ltd., Chichester, England, 2009.
74. C. Larman, Applying UML and Patterns: An Introduction to Object-Oriented Analysis

and Design and Iterative Development, Third Edition, Pearson Education, Inc., Upper Saddle River, NJ, 2005.
75. D. Lea, Concurrent Programming in Java, Second Edition, Addison-Wesley Longman,

Inc., Reading, MA, 2000.

76. D. Lee and W. W. Chu, Comparative analysis of six XML schema languages,

Department of Computer Science, University of California, Los Angeles, CA, June 2000. Online at: http://cobase-www.cs.ucla.edu/tech-docs/dongwon/ucla-200008.html
77. D. H. Lorenz and J. Vlissides, Pluggable reflection: Decoupling meta-interface and

implementation, Proceedings of the 25th International Conference on Software Engineering, Portland, OR, pp. 3, May 2003.
78. A. A. Lovelace, Translators notes to an article on Babbages Analytical Engine, In R.

Taylor (Editor), Scientific Memoirs, vol. 3, pp. 691-731, September 1843.

79. J. Maeda (Editor), Creative Code: Aesthetics + Computation, Thames & Hudson,

London, UK, 2004.

80. P. Maes, Concepts and experiments in computation reflection, ACM SIGPLAN Notices

(OOPSLA 87 Proceedings), vol. 22, no. 12, pp. 147-155, December 1987.
81. K. Malan and K. Halland, Examples that can do harm in learning programming,

Companion to the 19th Annual ACM SIGPLAN Conference on Object-oriented Programming Systems, Languages, and Applications (OOPSLA '04), Vancouver, BC, Canada, pp. 83-87, October 2004.
82. R. Malan, R. Letsinger, and D. Coleman, Object-Oriented Development at Work: Fusion

in the Real World, Prentice-Hall PTR, Upper Saddle River, NJ, 1996.
83. A. Marcoux, C. Maurel, F. Migeon, and P. Sall, Generic operational decomposition

for concurrent systems: Semantics and reflection, Progress in Computer Research, Nova Science Publishers, Inc., pp. 225-242, 2001.
84. R. C. Martin, Agile Software Development, Principles, Patterns, and Practices, Prentice

Hall, Upper Saddle River, NJ, 2003.

85. H. Masuhara and A. Yonezawa, Reflection in concurrent object-oriented languages,

Formal Methods for Distributed Processing: A Survey of Object-Oriented Approaches, Cambridge University Press, New York, NY, 2001.
86. J. McGovern, S. Tyagi, M. Stevens, and S. Mathew, Java Web Services Architecture,

Morgan Kaufmann Publishers, San Francisco, CA, 2003.

87. J. McGrenere, R. M. Baecker, and K. S. Booth, An evaluation of a multiple interface

design solution for bloated software, Proc. ACM CHI 2002, ACM CHI Letters, vol. 4, no. 1, pp. 164-170, 2002.

References

407

88. W. E. McUmber and B. H. C. Cheng, A general framework for formalizing UML with

formal languages, Proceedings of the IEEE/ACM International Conference on Software Engineering (ICSE01), Toronto, Canada, pp.433-442, May 2001.
89. A. J. Menezes, P. C. van Oorschot, and S. A. Vanstone, Handbook of Applied

Cryptography, CRC Press, LLC, Boca Raton, FL, 1997. Whole text available for download online at: http://www.cacr.math.uwaterloo.ca/hac/
90. B. Meyer, The dependent delegate dilemma, in M. Broy, J. Grnbauer, D. Harel, and

T. Hoare (Eds.), Engineering Theories of Software Intensive SystemsNATO Science Series II. Mathematics, Physics and Chemistry vol. 195, pp. 105-118, Springer, 2005.
91. G. A. Miller, The magical number 7 plus or minus two: Some limits on our capacity for

processing information, Psychological Review, vol. 63, pp. 81-97, 1957.

92. A. Mitchell and J. F. Power, Using object-level run-time metrics to study coupling

between objects, Proceedings of the 2005 ACM Symposium on Applied Computing (SAC '05), Santa Fe, NM, March 2005.
93. P. Mohagheghi, B. Anda, and R. Conradi, Effort estimation of use cases for

incremental large-scale software development, Proceedings of the 27th IEEE/ACM International Conference on Software Engineering (ICSE05), pp. 303-311, St Louis, MO, 2005.
94. M. C. Mozer, The Adaptive House, Department of Computer Science, University of

Colorado, Boulder, CO. Web page last visited in December 2004. Online at: http://www.cs.colorado.edu/~mozer/house/
95. P. Mulet, J. Malenfant, and P. Cointe, Towards a methodology for explicit composition

of metaobjects, ACM SIGPLAN Notices, vol. 30, no. 10, pp. 316-330, October 1995.
96. G. C. Murphy, D. Notkin, and K. Sullivan, Software reflexion models: Bridging the gap

between source and high-level models, ACM SIGSOFT Software Engineering Notes, vol. 20, no. 4, pp. 18-28, October 1995.
97. J. Mylopoulos, L. Chung, and B. Nixon, Representing and using nonfunctional

requirements: A process-oriented approach, IEEE Transactions on Software Engineering, vol. 23, no. 3/4, pp. 127-155, 1998.
98. S. Nageswaran, Test effort estimation using use case points, Cognizant Technology

Solutions Quality Week 2001, San Francisco, CA, June 2001. Online at: http://www.cognizant.com/html/content/cogcommunity/Test_Effort_Estimation.pdf
99. A. Newell and H. A. Simon, GPS: A program that simulates human thought, In H.

Billings (Editor), Lernende Automaten, Munich: R. Oldenbourg KG, pp. 109-124, 1961. Reprinted in: E. A. Feigenbaum, J. Feldman, and P. Armer (Editors), Computers and Thought, Menlo Park: AAAI Press; Cambridge: MIT Press, pp. 279-293, 1995.
100. A. Newell and H. A. Simon, Human Problem Solving, Prentice-Hall, Englewood Cliffs,

NJ, 1972.

Ivan Marsic

Rutgers University

408

101. T. J. Ostrand, E. J. Weyuker, and R. M. Bell, Where the bugs are, Proceedings of the

2004 ACM SIGSOFT International Symposium on Software Testing and Analysis (ISSTA '04), Boston, MA, pp. 86-96, July 2004.
102. D. OSullivan and T. Igoe, Physical Computing: Sensing and Controlling the Physical

World with Computers, Thomson Course Technology PTR, Boston, MA, 2004. See also Tom Igoes webpage on Physical Computing at: http://tigoe.net/pcomp/index.shtml
103. D. L. Parnas, On the criteria to be used in decomposing systems, Communications of

the ACM, vol. 15, no. 12, pp. 1053-1058, December 1972.
104. H. Petroski, The Evolution of Useful Things: How Everyday ArtifactsFrom Forks and

Pins to Paper Clips and ZippersCame to Be as They Are. Alfred A. Knopf, Inc., New York, NY, 1992.
105. J. Raskin, Comments are more important than code, ACM Queue, vol. 3, no. 2, pp. 64-

ff, March 2005.

106. J. Raskin, The Humane Interface: New Directions for Designing Interactive Systems,

ACM Press and Addison-Wesley, Reading, MA, 2000.

107. M. Richmond and J. Noble, Reflections on remote reflection, Australian Computer

Science Communications, vol. 23, no. 1, pp. 163-170, January-February 2001.

108. K. H. Rosen, Discrete Mathematics and Its Applications, Sixth Edition, McGraw-Hill,

New York, NY, 2007.

109. B. Sandn, Coping with Java threads, IEEE Computer, vol. 37, no. 4, pp. 20-27, April

2004.
110. M. Satyanarayanan and D. Narayanan, Multi-fidelity algorithms for interactive mobile

applications, Wireless Networks, vol. 7, no. 6, pp. 601-607, November 2001.

111. G. Schneider and J. P. Winters, Applying Use Cases: A Practical Guide, Second Edition,

Addison-Wesley Professional, Reading, MA, 2001.

112. L. M. Seiter, J. Palsberg, and K. J. Lieberherr, Evolution of object behavior using

context relations, ACM SIGSOFT Software Engineering Notes, vol. 21, no. 6, pp. 4657, November 1996.
113. B. C. Smith, Reflection and semantics in LISP, Proceedings of the 11th ACM

SIGACT-SIGPLAN Symposium on Principles of Programming Languages, Salt Lake City, UT, pp. 23-35, 1984.
114. B. C. Smith, Reflection and Semantics in a Procedural Language, Ph. D. thesis, MIT/-

LCS/TR-272, Cambridge, Massachusetts, January 1982. Available at: http://www.lcs.mit.edu/publications/specpub.php?id=840

115. I. Sommerville, Software Engineering, Seventh Edition, Addison-Wesley Publ. Ltd.,

Edinburgh Gate, England, 2004.

116. J. T. Stasko, J. B. Domingue, M. H. Brown, and B. A. Price (Editors), Software

Visualization: Programming as a Multimedia Experience, The MIT Press, Cambridge, MA, 1998.

References

409

117. W. R. Stevens, B. Fenner, and A. M. Rudoff, Unix Network Programming, Vol. 1: The

Sockets Networking API, Third Edition, Addison-Wesley (Pearson Education, Inc.), Boston, MA, 2004.
118. G. T. Sullivan, Aspect-oriented programming using reflection and metaobject

protocols, Communications of the ACM, vol. 44, no. 10, pp. 95-97, October 2001.
119. Sun Microsystems, Inc., JavaBeans API specification. Mountain View, CA, Available

at: http://www.javasoft.com/beans/
120. Sun Microsystems, Inc., JavaServer Pages. Mountain View, CA. Available at:

http://java.sun.com/products/jsp/index.html
121. Sun Microsystems, Inc., The Java Tutorial: A Practical Guide for Programmers,

1995-2005 Sun Microsystems, Inc., Last update: April 15, 2005. Online at: http://java.sun.com/docs/books/tutorial/index.html
122. B. K. Szymanski and G. Chen, A component model for discrete event simulation, in

R.Wyrzykowski, J. Dongarra, M. Paprzycki, and J. Wasniewski (Editors), Proceedings of the 4th International Conference Parallel Processing and Applied Mathematics (PPAM 2001), pp. 580-594, Naleczow, Poland, September 2001. Revised Papers appeared in Lecture Notes in Computer Science 2328, Springer-Verlag, 2002.
123. R. N. Taylor, N. Medvidovi, and E. M. Dashofy, Software Architecture: Foundations,

Theory, and Practice, John Wiley & Sons, Inc., Hoboken, NJ, 2010.
124. M. W. Tobias, Locks, Safes and Security: An International Police Reference, Second

Edition, Charles C. Thomas Publ. Ltd., Springfield, IL, 2000.

125. H.-Y. Tyan, A. Sobeih, and J. C. Hou, Towards composable and extensible network

simulation, Proceedings of the 19th International Parallel and Distributed Processing Symposium (IPDPS 2005), CD-ROM/Abstracts Proceedings, Denver, CO, April 2005.
126. K. J. Vicente, Cognitive Work Analysis: Toward Safe, Productive, and Healthy

Computer-Based Work, Lawrence Erlbaum Associates, Publishers, Mahwah, NJ, 1999.

127. M. Vlter, M. Kircher, and U. Zdun, Remoting Patterns: Foundations of Enterprise,

Internet and Realtime Distributed Object Middleware, John Wiley & Sons, Ltd., Chichester, England, 2005.
128. J. Waldo, G. Wyant, A. Wollrath, and S. Kendall, A Note on Distributed Computing.

Technical Report SMLI TR-94-29, Sun Microsystems Laboratories Inc., Mountain View, CA, November 1994. Available at: http://research.sun.com/techrep/1994/abstract29.html Also in: Lecture Notes In Computer Science; Vol. 1222: Selected Presentations and Invited Papers Second International Workshop on Mobile Object SystemsTowards the Programmable Internet, pp. 49-64, Springer-Verlag Publ., 1996.
129. R. T. Watson, M.-C. Boudreau, P. T. York, M. E. Greiner, and D. Wynn, Jr., The

business of open source, Communications of the ACM, vol. 51, no. 4, pp. 41-46, April 2008.

Ivan Marsic

Rutgers University

410

130. E. J. Weyuker, Evaluating software complexity measures, IEEE Transactions on

Software Engineering, vol. 14, no. 9, pp. 1357-1365, September 1988.

131. R. J. Whiddett, Concurrent Programming for Software Engineers, Chichester, West

Sussex: Ellis Horwood; New York: Halsted Press, 1987.

132. R. Wirfs-Brock and A. McKean, Object Design: Roles, Responsibilities, and

Collaborations, Addison-Wesley, Boston, MA, 2003.

133. A. Wollrath, R. Riggs, and J. Waldo, A distributed object model for the Java system,

USENIX Computing Systems, vol. 9, no. 4, Fall 1996.

134. J. Woodcock and M. Loomes, Software Engineering Mathematics: Formal Methods

Demistifyed, Pitman, 1988.

Acronyms and Abbreviations

Note: WhatIs.com provides definitions, computer terms, tech glossaries, and acronyms at: http://whatis.techtarget.com/ A2A Application-to-Application AES Advanced Encryption Standard AI Artificial Intelligence AOP Aspect-Oriented Programming API Application Programming Interface AWT Abstract Widget Toolkit (Java package) AXIS Apache eXtensible Interaction System B2B Business-to-Business BOM Business Object Model BPEL4WS Business Process Execution Language for Web Services CA Certification Authority CBDI Component Based Development and Integration CDATA Character Data CORBA Common Object Request Broker Architecture COTS Commercial Off-the-shelf CPU Central Processing Unit CRC Candidates, Responsibilities, Collaborators cards CRM Customer Relationship Management CRUD Create, Read, Update, Delete CSV Comma Separated Value CTS Clear To Send DCOM Distributed Component Object Model DOM Document Object Model DTD Document Type Definition EJB Enterprise JavaBean FSM Finite State Machine FTP File Transfer Protocol FURPS+ Functional Usability Reliability Performance Supportability + ancillary GPS General Problem Solver; Global Positioning System GRASP General Responsibility Assignment Software Patterns GUI Graphical User Interface HTML HyperText Markup Language HTTP HyperText Transport Protocol HTTPS Hypertext Transfer Protocol over Secure Socket Layer IDE Integrated Development Environment IDL Interface Definition Language IEEE Institute of Electrical and Electronics Engineers IP Internet Protocol IPv4 Internet Protocol version 4 IT Information Technology JAR Java Archive JDBC Java Database Connectivity JDK Java Development Kit JRE Java Runtime Environment JSP Java Server Page JVM Java Virtual Machine LAN Local Area Network MDA Model Driven Architecture MIME Multipurpose Internet Mail Extensions MVC Model View Controller (software design pattern) OASIS Organization for the Advancement of Structured Information Standards OCL Object Constraint Language OMG Object Management Group OO Object Orientation; Object-Oriented OOA Object-Oriented Analysis OOD Object-Oriented Design ORB Object Request Broker OWL Web Ontology Language PAN Personal Area Network PC Personal Computer PCDATA Parsed Character Data PDA Personal Digital Assistant QName Qualified Name (in XML) QoS Quality of Service P2P Peer-to-Peer PI Processing Instruction (XML markup) PKI Public Key Infrastructure RDD Responsibility-Driven Design RDF Resource Description Framework

411

Ivan Marsic

Rutgers University

412 UML Unified Modeling Language URI Unified Resource Identifier URL Unified Resource Locator URN Unified Resource Name UUID Universal Unique Identifier VLSI Very Large Scale Integration W3C World Wide Web Consortium WAP Wireless Access Protocol WEP Wired Equivalent Privacy WG Working Group Wi-Fi Wireless Fidelity (synonym for IEEE 802.11) WML Wireless Markup Language WS Web Service WSDL Web Services Description Language WWW World Wide Web XMI XML Metadata Interchange XML eXtensible Markup Language XP eXtreme Programming XPath XML Path XSL eXtensible Stylesheet Language XSLT eXtensible Stylesheet Language Transform

RFC Request For Comments; Remote Function Call RFID Radio Frequency Identification RMI Remote Method Invocation (Java package) RPC Remote Procedure Call RSS Really Simple Syndication RTS Request To Send RTSJ Real-Time Specification for Java RUP Rational Unified Process SE Software Engineering SGML Standard Generalized Markup Language SMTP Simple Mail Transfer Protocol SOA Service Oriented Architecture SOAP Simple Object Access Protocol; Service Oriented Architecture Protocol; Significantly Overloaded Acronym Phenomenon SSL Secure Socket Layer SuD System under Discussion TCP Transport Control Protocol TDD Test-Driven Development TLA Temporal Logic of Actions UDDI Universal Description, Discovery, and Integration UDP User Datagram Protocol

Index

CDATA [ XML/DTD ]

Symbols
(and) (exists) (for all) (if and only if) (implies) (not) (or)

DOCTYPE [ XML/DTD ] ELEMENT [ XML/DTD ] FIXED [ XML/DTD ] IMPLIED [ XML/DTD ] PCDATA [ XML/DTD ] REQUIRED [ XML/DTD ]

Java Classes
ArrayList [ java.util.* ] AttributeList [ org.xml.sax.* ] BufferedReader [ java.io.* ] Class [ java.lang.* ] Constructor [ java.lang.reflect.* ] DocumentHandler [ org.xml.sax.* ] Field [ java.lang.reflect.* ] HashMap [ java.util.* ] Hashtable [ java.util.* ] InputStream [ java.io.* ] InputStreamReader [ java.io.* ] IOException [ java.io.* ] Iterator [ java.util.* ] Method [ java.lang.reflect.* ] OutputStreamWriter [ java.io.* ] Parser [ org.xml.sax.* ] PrintWriter [ java.io.* ] Serializable [ java.io.* ] SerialPort [ javax.comm.* ] ServerSocket [ java.net.* ] Socket [ java.net.* ] TooManyListenersException [ java.util.* ] Vector [ java.util.* ]

A
Absolute scale. See Scales Abstraction Access control Activity diagram Actor Offstage Primary Supporting Adaptive house Aggregation Agile method Agile planning Algorithm Analysis Applet Application Architectural style Architecture, software Artifact Artificial intelligence Aspect-Oriented Programming Association Attribute Authentication Autonomic computing

XML Keywords
ANY [ XML/DTD ] ATTLIST [ XML/DTD ]

413

Ivan Marsic

Rutgers University Correctness Cost estimation Critical region Cross-cutting concern Cryptography Cryptosystem Public-key Symmetric

414

B
Bean. See Java Beans Binding Biometrics Black box Boundary, system Broker pattern. See Design patterns Brooks, Frederick P., Jr. Bug

D C
Chunking Ciphertext Class Abstract Base Derived Inner Class diagram Client object Code Cohesion Command pattern. See Design patterns Comment Communication diagram Complexity Cyclomatic Halsteads method McCabe Size-based metrics Component Component diagram Composite Composition Concept Conceptual modeling Conclusion Concurrent programming Conjunction Constraint Constructor Content model Context diagram Contract Contradiction Controller. See Design patterns Coordination Coupling Data structure Data-driven design Decryption Defect Delegation Delegation event model De Morgans laws Dependency Design Design patterns Behavioral Broker Command Controller GRASP Observer Proxy Publish-Subscribe Structural Diffie-Hellman algorithm Disjunction Distributed computing Divide-and-conquer. See Problem solving Document, XML Documentation DOM Domain layer Domain model Domain object

E
Effort estimation Embedded processor Emergent property, system Encapsulation Encryption Equivalence Error

Index Estimation. See Project estimation Ethnography Event Keyboard focus Event-driven application Exception Existential quantification Expert rule Extension point Extreme programming Integration testing Interaction diagram Interface, software Interval scale. See Scales Interview, requirements elicitation Introspection Instruction Iterative lifecycle

415

J
Jackson, Michael Java, programming language Java Beans JUnit

F
Failure Fault Fault tolerance Feature, system Feynman, Richard P. Fingerprint reader Finite state machine Fixture (in testing) Formal specification Frame Framework Functional requirement FURPS+, system requirements

K
Keyboard Keyword Kleene operators

L
Latency Layer Layered architecture Layout Lifecycle, software Lifeline Link Listener Logic

G
Generalization Goal specification Graph theory Graphical user interface GRASP pattern. See Design patterns

M
Maintenance Markup language Marshalling Menu Message Messaging Metadata Metaphor Method Middleware Miller, George A. Minimum Description Length problem Model Model Driven Architecture Modular design Multithreaded application

H
Handle Heuristics HTML HTTP Human working memory Hypothesis

I
Implementation Implication Indirection Inheritance Input device Instance, class

Ivan Marsic

Rutgers University Productivity factor Program Project estimation Project management Property Access Editor Propositional logic Protocol Prototype Proxy pattern. See Design patterns Public-key cryptosystem. See Cryptosystem Publisher-subscriber pattern. See Design patterns Pull vs. push

416

Mutual exclusion (mutex)

N
Namespace, XML Naming service Navigability arrow Negation Network Local Area Network (LAN) Wireless Network programming Node Nominal scale. See Scales Non-functional requirement

O
Object, software Object Request Broker (ORB). See Broker pattern Observer pattern. See Design patterns OMG (Object Management Group) Ontology OOA (Object-oriented analysis) OOD (Object-oriented design) Operation Operator, logical Ordinal scale. See Scales

Q
Qualified name (QName) Quantifier Query Queue Quote tag, XML

R
Ratio scale. See Scales Reactive application. See Event-driven application Real-time specification for Java (RTSJ) Refactoring Reference Reflection Registry, naming Reifying Relationship, class Is-a Part-of Uses-a Remote Method Invocation (RMI) Remote object Requirement Requirements elicitation. See Requirements gathering Requirements engineering Requirements gathering Requirements specification Responsibility Responsibility-driven design Reuse Reversible actions RFID Risk analysis

P
Package Package diagram Parnas, David L. Parsing Pattern. See Design patterns Pen, as input device Performance Persistence Petri nets Plaintext Polymorphism Port Postcondition Precondition Predicate logic Premise Problem frame Problem solving Process Processing instruction, XML

Index Role RS-232. See Serial port Rule-based expert system

417

T
Tablet Tautology Test-driven development (TDD) Testing All-edges coverage All-nodes coverage All-paths coverage Black-box Coverage-based Test driver Test stub White-box Thread Synchronization Tiered architecture TLA+ specification language Tool Toolkit Transition diagram Translation Transformation Inverse Trapdoors function Traversal, graph Tree data structure Typecasting

S
Safety, thread Scale types Absolute Interval Nominal Ordinal Ratio Schema, XML Scope, name Security Semantics Sensor Separation of concerns Sequence diagram Serial port Server object Service Service-Oriented Architecture (SOA) Servlet, Java SGML (Standard Generalized Markup Language) Skeleton SOAP Socket, network Software development process Software engineering Software lifecycle Stakeholder State, object State machine diagram State variable Stereotype Story points. See User story points Stub Symbol, UML System Behavior Boundary State System sequence diagram System under discussion (SuD) System use case

U
UML, See Unified Modeling Language Undo/redo Unified Modeling Language (UML) Unified Process Unit testing Universal quantification UP. See Unified Process Usage scenario Use case Alternate scenario Detailed description Instance Main success scenario Schema Use case diagram Use case points User User story User story points

Ivan Marsic

Rutgers University Wicked problem Window Wizard-of-Oz experiment

418

V
Validation Verification Velocity Version control Visibility Vision statement Visual modeling

X
XLink XML XPath XSLT

W
Wait set, threads Waterfall methodology Web method Web service Web Services Definition Language (WSDL)

Y Z
Z specification language