Chapter 11: Operation Contracts

1
Chapter 11 Operation Contracts

• 11.1. Introduction
• Use cases or system features are the main ways in
  the UP to describe system behavior, and are
  usually sufficient. Sometimes a more detailed or
  precise description of system behavior has value.
  Operation contracts use a pre- and post-condition
  form to describe detailed changes to objects in a
  domain model, as the result of a system
  operation.
• See Figure 11.1 contracts within the UP.
• Contracts serve as input to the object design, as
  they describe changes that are required in the
  software objects
• they are also a great to validate the domain
  model and, to a lesser extent, the use cases
• validating, looking for omissions, errors etc. on
  an on-going basis is very important in an agile
  approach never assume that the documents are
  prefect never freeze an artifact

2
Figure 11.1 contracts within the UP
3

• 11.2 Example
• SSDs identify system operations, one of these was
  the enterItem system operation. The critical
  element is the postconditions the other parts
  are useful but less important
• Contract CO2 enterItem
• Operation enterItem(itemID ItemID, quantity
  integer)
• Cross References Use Cases Process Sale
• Preconditions There is a sale underway.
• Postconditions
• A SalesLineItem instance sli was created
  (instance creation).
• sli was associated with the current Sale
  (association formed).
• sli.quantity became quantity (attribute
  modification).
• sli was associated with a ProductDescription,
  based on itemID match (association formed).

4

• 11.3 Identifying System Operations
• System operations can be identified while
  sketching SSDs.
• Input system events imply the system has system
  operations to handle the events, just as an OO
  message (a kind of event or signal) is handled by
  an OO method (a kind of operation).
• The entire set of system operations, across all
  use cases, defines the public system interface,
  viewing the system as a single component or
  class. In the UML, the system as a whole can be
  represented as one object of a class named (for
  example) System.
• See Figure 11.2 for system operations with an
  SSD.

5

Figure 11.2 Identifying System Operations
6

• 11.4 Postcondition Section of a Contract
• The postconditions describe changes in the state
  of objects in the domain model. Domain model
  state changes include instances created,
  associations formed or broken, and attributes
  changed.
• The postconditions must be concerned with the
  domain model
• we exclude user interface matters in the
  postconditions we must just ensure that the
  information to displayed (or produced) is
  available in the domain model
• the postconditions must reflect the changes that
  will occur in the domain model of the application
  after the operation has completed
• Writing contracts is a great way to validate the
  domain model
• To be systematic try to annotate your
  postconditions with one of the following
  category
• Instance creation and deletion
• Attribute change of value
• Associations formed and broken

7

• Breaking associations is rare. But as an example,
  consider an operation to allow the deletion of
  line items. The postcondition could read "The
  selected SalesLineItem's association with the
  Sale was broken." In other domains, when a loan
  is paid off or someone cancels their membership
  in something, associations are broken.
• Again the postconditions are expressed in the
  context of the Domain Model objects. What
  instances can be created? those from the Domain
  Model What associations can be formed? those in
  the Domain Model and so on.
• The most common mistakes during contract creation
  are
• Not writing them at all
• Being too sloppy everything must refer back to
  the domain model
• Not modifying the Domain Model whenever
  necessary
• Forgetting to include the formation of
  associations
• Spending too much time (more than 10 minutes) on
  them for no valid reason

8

• 11.5 Contract within an agile Context
• Contracts are not always necessary
• most often, the effect of a system operation is
  relatively clear to the developers by virtue of
  reading the use case, talking with experts, or
  their own knowledge. But sometimes more detail
  and precision is useful. Contracts offer that
• Further, whenever they are useful, generating a
  complete and detailed set of postconditions for
  all system operations is not necessary. In the
  spirit of Agile Modeling, treat their creation as
  an initial best guess
• But understanding that light analysis is
  realistic and skillful doesn't mean to abandon a
  little investigation before programming that's
  the other extreme of misunderstanding.
• 10 minutes writing a contract may yield powerful
  insights about the application, detect
  insufficiencies in the domain model etc. if
  every thing is clear and consistent spending more
  time than this is wasteful and not in the agile
  spirit of software development.

9

• A contract is an excellent tool of requirements
  analysis or OOA that describes in great detail
  the changes required by a system operation (in
  terms of the domain model objects) without having
  to describe how they are to be achieved In other
  words, the design can be deferred, and we can
  focus on the analysis of what must happen, rather
  than how it is to be accomplished.
• For example in
• A SalesLineItem instance sli was created
  (instance creation).
• sli was associated with the current Sale
  (association formed).
• sli.quantity became quantity (attribute
  modification).
• sli was associated with a ProductDescription,
  based on itemID match (association formed).
• No comment is made about how a SalesLineItem
  instance is created, or associated with a Sale.
  (This could be a statement about writing on bits
  of paper and stapling them together, using Java
  technologies to create software objects and
  connect them, or inserting rows in a relational
  database)

10

• 11.6 How to Write Postconditions?
• Express postconditions in the past tense to
  emphasize they are observations about state
  changes that arose from an operation, not an
  action to happen. For example
• (better) A SalesLineItem was created.
• rather than
• (worse) Create a SalesLineItem, or, A
  SalesLineItem is created.
• Analogy The Stage and Curtain Think about the
  postconditions using the following image
• The system and its objects are presented on a
  theatre stage.
• Before the operation, take a picture of the
  stage
• Close the curtains on the stage, and apply the
  system operation
• Open the curtains and take a second picture
• Compare the before and after pictures, and
  express as postconditions the changes in the
  state of the stage (A SalesLineItem was
  created).

11

• 11.7 enterItem Postconditions
• Instance Creation and Deletion
• After the itemID and quantity of an item have
  been entered, what new object should have been
  created? A SalesLineItem. Thus
• A SalesLineItem instance sli was created
  (instance creation)
• Note the naming of the instance. This name will
  simplify references to the new instance in other
  post-condition statements.
• Attribute Modification
• After the itemID and quantity of an item have
  been entered by the cashier, what attributes of
  new or existing objects should have been
  modified? The quantity of the SalesLineItem
  should have become equal to the quantity
  parameter. Thus
• sli.quantity became quantity (attribute
  modification)

12

• Associations Formed and Broken
• After the itemID and quantity of an item have
  been entered by the cashier, what associations
  between new or existing objects should have been
  formed or broken? The new SalesLineItem should
  have been related to its Sale, and related to its
  ProductDescription. Thus
• sli was associated with the current Sale
  (association formed)
• sli was associated with a ProductDescription,
  based on itemID match
• (association formed)
• This all quite systematic
• It is systematic here because the domain model
  contains all the information that needs to be
  updated
• If there were problems in the domain model they
  would quickly be revealed using this approach
  all the benefits of contracts
• If there are problems, the domain model should be
  modified thats a benefit of an
  evolutionary/iterative software development
  method all artifacts are considered partial and
  imperfect and evolve in response to new
  discoveries.

13

• 11.8 POS Contracts
• Contract CO1 makeNewSale
• Operation makeNewSale()
• Cross References Use Cases Process Sale
• Preconditions none
• Postconditions
• A Sale instance s was created (instance
  creation).
• s was associated with a Register (association
  formed).
• Attributes of s were initialized (attribute
  modification).

14

• Contract CO2 enterItem
• Operation enterItem(itemID ItemID, quantity
  integer)
• Cross References Use Cases Process Sale
• Preconditions There is a sale underway.
• Postconditions
• A SalesLineItem instance sli was created
  (instance creation).
• sli was associated with the current Sale
  (association formed).
• sli.quantity became quantity (attribute
  modification).
• sli was associated with a ProductDescription,
  based on itemID match (association formed).
• Contract CO3 endSale
• Operation endSale()
• Cross References Use Cases Process Sale
• Preconditions There is a sale underway.
• Postconditions
• Sale.isComplete became true (attribute
  modification).

15

• Contract CO4 makePayment
• Operation makePayment( amount Money )
• Cross References Use Cases Process Sale
• Preconditions There is a sale underway.
• Postconditions
• A Payment instance p was created (instance
  creation).
• p.amountTendered became amount (attribute
  modification).
• p was associated with the current Sale
  (association formed).
• The current Sale was associated with the Store
  (association formed) (to add it to the
  historical log of completed sales)
• Discussion
• At least one change is required in the Domain
  Model we did not initially discover that we
  needed to record the fact that the processing of
  the items was over
• We need to add a isComplete attribute to the Sale
  concept

16

• 11.9 Monopoly Contracts
• The PlayGame system operation could be described
  by a contract but it is, in effect, already
  captured by the game rules described in the
  requirements document in this case a contract is
  not necessary as it will not bring any additional
  information.
• 11.10 Contract within the UP
• Inception Contracts are not motivated during
  inception they are too detailed.
• Elaboration If used at all, most contracts will
  be written during elaboration, when most use
  cases are written. Only write contracts for the
  most complex and subtle system operations.

17

• 11.11 Conclusions
• As seen, contracts serve as input to the object
  design, as they describe changes that are
  required in the software objects
• they are also a great to validate the domain
  model and, to a lesser extent, the use cases
• validating, looking for omissions, errors etc. on
  an on-going basis is very important in an agile
  approach never assume that the documents are
  prefect never freeze an artifact
• They are a valuable artefact but not too much
  time should be spent on them in straightforward
  cases
• Questions Please