14 1 Introduction

the overall picture assumes a concrete form – the sequence diagram – instead of existing only in the mind of the programmer who understands the code. For larger systems, the support coming from these diagrams is potentially even more important, given the cognitive difficulties of humans confronted with a large number of interacting entities.

The construction of collaboration and sequence diagrams is presented in Chapter 5. An algorithm for the computation of the Dewey numbers associated with the method calls is described in the same chapter. It determines the flow of the events in sequence diagrams. A focusing method to produce diagrams for specific computations of interest is also provided.

1.6 State Diagrams

State diagrams are used to represent the states possibly assumed by the objects of a given class, and the transitions from state to state possibly triggered by method invocations. The joint values of an object’s attributes define its “complete” state. However, it is often possible to select a subset of all the attributes to characterize the state. Moreover, the set of all possible values can usually be abstracted into a small set of symbolic values. In this way, the size of the state diagrams can be kept limited, fitting the cognitive abilities of humans.

Fig. 1.5. State diagram for class Document (left) and User (right).

The state of an object of class Document of the eLib program can be characterized by the physical presence/absence of the related item in the library.

1.6 State Diagrams

15

Different behaviors are obtained by invoking methods on a Document object, when such an object is available for loan, rather than being out, borrowed by some library user.

Among the attributes of class Document, the one which characterizes the state of its objects is loan. In fact, a null value of loan indicates that the document is available for loan, while a non null value indicates that the document is currently borrowed, with the related Loan object referenced by the attribute loan.

Fig. 1.5 (left) shows the state diagram reverse engineered from the code of class Document. Its two states and indicate respectively the situation where the document is available for loan (tagged value loan=null in braces) or is loaned (tagged value loan=Loan1). Initially, the document is available (edge from the initial state, indicated as a small solid filled circle, to

Interesting information conveyed by Fig. 1.5 (left) regards the states in which method calls can be accepted. In state (document available) the only admitted operation is addLoan. It is not possible to request the removal

of a loan associated to	the given Document in state		On the other side,
when the document is	loaned (state	the only admitted operation is the

closure of the loan (removeLoan), and no request can be accepted to borrow the given document (no call of addLoan admitted). This is consistent with the intuitive semantics of document borrowing: it makes no sense returning available documents as well as borrowing loaned documents.

The state of the objects that belong to the class User is identified by the values of the attribute loans, which records the set of loans a given library

user	has made. Since this attribute is a container of objects of the type Loan,
it is	possible to abstract its concrete values into three symbolic values: empty

(no element in the container), one (exactly one element in the container) and many (more than one element in the container).

Fig. 1.5 (right) shows the state transitions that characterize the lifetime of the objects of class User. Initially, they are associated to no loan (edge from the small solid filled circle to In this state the removeLoan operation is not admitted, and the only possibility is to add a new loan, by invoking the method addLoan. This corresponds to the expected behavior of a User object, which initially can only be involved in borrowing documents, and not in returning them.

When the User object contains exactly one Loan (state it is possible to close it, by returning the related document (call to removeLoan) and moving

it back to state		or to add another loan (call to addLoan), moving it to the
state	which represents more than one document loaned by a given user.
Finally, in state		the addition of further loans does not modify the state

of the given object, while the closure of a loan (removeLoan) may either trigger

the transition to state	if after the removal only one loan remains, or to
itself.

Similar to the class Document, some preconditions on the admitted method invocations are revealed by the state diagram for class User. In particular, no

16 1 Introduction

call to removeLoan is accepted in the state assumed by a User object after its creation when no loan has yet been created by the given user.

Fig. 1.6. State diagram for class Library.

The state of the objects of the class Library is characterized by the joint values assumed by the class attributes documents, users and loans. The attribute documents contains a mapping from document identifiers (documentCode) to the related Document objects stored in the library. Similarly, users holds the mapping from user identifiers (userCode) to User objects. Thus, they can be regarded as containers, storing documents possessed by the library and the users registered in the library.

The attribute loans is a container of type Collection, which maintains the set of currently active loans in the library. A Loan references the library user who requested the document as well as the borrowed document.

Since the three attributes documents, users and loans are containers of other objects, it is possible to abstract the values they can assume by means of two symbolic values: indicating an empty container, and indicating that some (i.e., one or more) objects are stored inside the container. Thus, the joint values of the three considered attributes is represented by a triple,

such as	whose elements correspond respectively to documents,
users and loans (thus,		should read documents = empty, users =
some, loans =	empty).

Fig. 1.6 shows the state diagram of class Library, characterized by the triples of joint values of documents, users and loans. When no user is yet registered and no document is available in the library, invocations of

			1.6 State Diagrams		17
addDocument and addUser change the initial state			into	or	respec-
tively. Addition of a new user in		or of a document in		moves the	library
into state	where some users are registered and some documents are avail-
able. Transitions among the states		are achieved by calling meth-

ods addUser, removeUser, addDocument, removeDocument. No special constraint is enforced with respect to such method invocations. Of course, removal methods have no effect when containers are empty (e.g., removeDocument in state

Overall, the four topmost states in Fig. 1.6 describe the management of users and documents. The librarian can freely add/remove users and docu-

ments, changing the library state from			to
Creation	or	deletion of a loan is possible only in state		where some
documents	are	available in the library and some users are		registered. This
is indicated by the absence of edges labeled addLoan in the				states
of the state diagram and by the presence of such an edge				in the state
(as well as		Actually, the corresponding precondition on the invocation of

addLoan is checked by the calling methods. In the source code for the eLib program (see Appendix A), the only invocation to addLoan is at line 61 inside borrowDocument. This call is preceded by a check to verify that the involved User object and Document object (parameters of borrowDocument obtained from the library at lines 438, 439) be not null. This ensures that no call to addLoan is issued when no related user or document data are stored in the library.

Another interesting information that can be obtained from the state diagram in Fig. 1.6 is about the methods that can be invoked in In this state, the library holds some documents, it has some registered users, and some loans are active. It is not possible to reach any of the states directly from The only reachable state is which becomes the new state of the library when all active loans are removed. In other words, the state diagram constrains the legal sequences of operations that jointly modify users, documents and loans. Before removing all of the users or documents from the library, it is necessary to close all of the active loans.

The code implements the rules described above by performing some checks before proceeding with the removal of the given item from the respective container. As regards the method removeUser, at line 17, the number of loans associated with the user being removed is requested, and if it is greater than zero, the removal operation is aborted. Similarly, inside removeDocument, at line 33 the removal operation is interrupted if the document is out (i.e., some loan is associated with it). Thus, before deleting a user, all of the related loans must be closed, i.e., users can unregister from the library only if all of the documents they borrowed have been returned. Dually, documents can be dismissed only after being returned by the users who borrowed them. These two constraints on the joint values of the attributes document, users, loans are revealed by the transitions outgoing from state in the state diagram.