In this section we use the animator to test the behaviour of customers and accounts together with the Traditional and Credit contracts.
The animator allows to create objects, call methods, and trace them in a message sequence diagram. The animator uses the concept of project to manage a set of objects of given classes. The first step is therefore to create a project and load the necessary classes.
Start the animator by selecting Tools->Animator... in CDE.
Select File->New Animation Project and use the opened file dialog to create a file tour.apr in directory demos/tour.
The new project root appears on the left pane. Right-click on it and select Properties.
A dialog appears to edit the class path of the project, i.e., the list of directories where the animator will look for classes for this project. Click Add and then select the classes subdirectory. Finally, click OK on the properties dialog.
Now we can load the classes for this project, There are two ways to do it:
From the context menu for the project root, select Load Classes... .
Select Load Classes... from the File menu.
A list of all classes that were compiled in the previous section appears.
Select (i.e., turn the check marks on for) the Bank.Account, Bank.Customer,
cde.contracts.Credit, and cde.contracts.Traditional
classes, and click OK. Notice that the project root has now a handle. If you
expand the root node, these classes now appear on the left pane as children
of the project root.
To see how contracts work we must create concrete instances (i.e., objects) of the loaded classes. This will be done in a straightforward way by calling the constructors of the classes.
Right-click on the Account node and select Execute... from the context menu. An execution window appears.

It lets you call a method of (a
given instance of) the class for which this window was opened. Since there
are no instances yet, only class methods are available, and the only one for
Account is the constructor. Below the operation name
there is a set of text fields to fill in the arguments of the method to be
called. To the left of each field is the type of the argument. The argument
name is not shown because it is not stored by Java in class files. In this
case, the only argument to the Account constructor is a long integer (the unique
account number).
Write 1 in the text field.
Click Execute. The execution window has changed: the newly created instance has been automatically selected. Don't close the execution window, because we will further on execute operations on this account.
Notice also that the Account node on the left pane now has a handle on its
left. Click on it to expand the node and a child node for the account just
created will appear. The name of the node is "1" because the toString()
method of Account just returns the account number. Expand the account
instance node to see the list of operations
performed on it. For the moment, the only operation listed is the constructor
call with argument 1. The left pane should now look like this:

Now we create a customer and establish an ownership relation between both objects.
Right-click on the Customer node on the left pane, select Execute... and in the new execution window write 1 and Mary as first and second arguments to the constructor, and click on the Execute button.
The window has been updated: the selected instance is the new customer.
Select the addAccount method. Since the argument is an Account
object, there is no text box but a drop down menu instead, with all objects
of that class in the project: in this case the only existing account.

Click Execute and then Close. In the project pane, expand the Customer class node and then the node for Mary: a node named "addAccount(1)" was added to the history of operations.
The animator allows us to see in a glance all objects that exist of a given class, which is called the population of that class.
Right-click on the account node on the project tree. Select Population... . A new window appears on the right pane, showing a list of all accounts (only one for the moment), together with the values of the account attributes. You may change the width of columns by dragging the column edges. You may change the order of columns by dragging the column headers right or left to their new position.

Do the same for the Customer, Credit and Traditional classes. The tables for the contract classes will be empty for the moment.
To watch the execution of operations, the animator provides simplified message sequence diagrams. First we have to create the diagram window and add the objects we want to observe. Then we can start invoking operations on the objects in the project: any operations performed on the observed objects will be shown in the diagram. If an object in the diagram calls an operation on an object not present in the diagram, that object will automatically be added to the diagram.
Select File->New->Sequence Diagram. An empty tabbed window titled "Diagram 1" appears on the right pane.
In the project tree, right-click on the account object, and select Add to diagram from the context menu. From now on, all methods on account 1 will be traced.
In the Account execution window, select the withdraw method, set 100 as the first
argument and click the Execute button.
In the sequence diagram, the arrows indicate messages, and the boxes indicate
methods. An arrow shaft with a diamond means the message was sent from outside
the objects. Nesting of calls is not shown in this version, and therefore a box
only states that the method given by the box label has been called, not that it
also has completed. In this case, for example, the ownedBy method is executed before withdraw
returns.
At the bottom of the diagram there are 8 buttons. The two left-most buttons allow to change the order of the objects in the diagram. For that, first the object has to be selected by clicking on its label at the top. The box and lifeline become red. Now one can use the left and right arrow buttons to swap the selected object with the one on its left or right. The arrows across lifelines are automatically redrawn. To deselect the object, click anywhere on the diagram except object headings. The buttons labeled Up and Down scroll the diagram up or down one event (message or method) at a time, maintaining the labels at the top of diagram always visible (whereas using the scrollbar on the right will scroll the whole picture of the diagram up or down). The Top button shows all events, starting from the first one. The Clear button makes all events disappear from the diagram. The two right-most buttons shrink and grow the diagram.
If you now switch to the Account population window, you can see that the account's balance is -100. This happened because there is no contract between the account and the customer, and therefore any withdrawal is possible. We now introduce a Traditional contract.
Create a new instance of the Traditional class, executing its constructor: the arguments are automatically set to the existing customer and account, because there is no other possibility. Don't close the Traditional execution window.
Add the Traditional instance to the diagram.
Click on Execute in the Account execution window, to perform another withdrawal of 100 Euros. This time the diagram shows that the withdraw operation was triggered but not executed: the Withdraw rule in the contract failed. However, since the rule has no body, there is no execution to show in the diagram. The exception raised is caught by the animator and displayed in the message area at the bottom of the window.
Select the Delete method in the Traditional execution window, and execute it. This method inactivates a contract permanently.
Perform another withdraw. It succeeds because it wasn't intercepted by the contract; the account balance is now -200.
Close the Traditional execution window.
Right-click on the Traditional object and select from the context menu the Delete Instance option.
The sequence diagram shows a generic destructor: a delete
message and method followed by a cross. Click on
the header of the Traditional object to select it: it becomes red. Now
right-click on the header and and select Delete from the context menu. The
Traditional lifeline disappears from the diagram.
Now we try a Credit contract.
Create a new instance of the Credit class. Again, don't close the execution window.
Add the object to the diagram.
Perform a withdrawal (of 100 Euros as usual) on the account. It won't succeed because the credit limit by default
is zero (see the column limit in the Credit population window).
In the Credit execution window, select the setlimit method
and give 300 as argument. See how the corresponding cell is updated in the
population window.
Perform the same withdrawal again. It will succeed and the account's balance is now -300, as can be seen in the Account population window.
Execute another withdraw, by any amount. It will not change the account because the credit limit has been reached.
Deposit 400 Euro (by executing the deposit/2 operation in the
account execution window) to prepare for the next scenario.
Next we try the LimitedTraditional in addition to the Credit contract.
Load the class cde.contracts.LimitedTraditional into the project and
create a new instance.
Withdraw 200 Euro and watch the diagram and population windows. Only 100 Euro are withdrawn, the balance becomes zero.
Notice the exact arrows and boxes shown in the diagram.

The first arrow indicates the withdraw message, which will trigger two rules:
WithdrawRule in the Credit contract and LimitedWithdraw in the
LimitedTraditional contract instance. When more than one rule is triggered for
the same message, the joint behaviour is as follows. First, all guards are
evaluated; if any of them is false, the corresponding failure code is executed
and that finishes the processing of the trigger. If all guards are true, then
all before actions are executed, the do action of the
oldest contract (i.e., the first that was created) is executed, and finally all after
actions are executed. In our example, there is only one guard (in the Credit
contract), which happens to be true; hence, execution proceeds with the before
action of the LimitedTraditional contract. Next the do action is
performed, which leads to the execution of the withdraw method,
which in turn calls the ownedBy method. Note that
the diagram shows which object triggered each contract rule: in this case the
arrows have origin in the Account object.
Now try to withdraw 400 Euro. As the balance is zero, the guard of the Credit contract is false (because the balance cannot become -400, which is lower than the limit), and hence the actions of the LimitedTraditional contract are not executed.
If you wish, you may continue playing around with various combinations of contracts and components. Suggestions are given in the exercises. Once you have finished, save the project and exit the animator.
Select File->Save Animation Project. Note that this will only save the information about the classes that belong to the project. The actual objects that have been created are not saved.
Select File->Exit.
To practice working with the animator, here are some scenarios to explore. For each one, you can start from scratch (e.g., by closing the project and then re-opening it) or continue from the previous scenario. First, read the scenario and try to guess what will happen. Then, as you go through the scenario, don't forget to check the diagram and population windows after each operation to see what happened.
One customer owns one account, and there is only a LimitedTraditional contract between them. The account has 200 Euro and 200 are withdrawn twice. Add a Traditional contract and repeat.
There is one customer and two accounts. The customer only owns one of them, the other doesn't belong to anyone. We refer to it as the "free" account. There is a Credit contract between the customer and the free account, with a credit limit of 100 Euro. There is a Traditional contract between the customer and her/his account. Both accounts have 200 Euro. There are two withdrawals on each account. First 100 and then 200 Euro. Add the customer to the "free" account and repeat.
There is one customer, and s/he owns one account. There is a Traditional and a Credit contract (with limit 100 Euro) between them. The account has 10 Euro, and 50 are withdrawn.
There are two customers and one account, owned by both customers. There is a Traditional contract between the account and the first owner. The account has 40 Euro, and the second owner withdraws 50. Add a LimitedTraditional contract between the account and the second customer, and repeat the withdrawal.
The animator allows to quickly test several coordination scenarios without building a special-purpose application. In particular, the animator allows to: