This repository contains examples of usage of the Contract Automata Runtime Environment (CARE).
Check the repository of CARE for more info https://github.com/ContractAutomataProject/CARE
This is a simple example used for evaluating the Contract Automata Runtime Environment (CARE).
Two implementations of the example are available for this example, and are located in src/main/java/io/github/contractautomata/care/examples/alicebob. The contract automata are under the folder /resources/alicebob.
The implementation src/main/java/io/github/contractautomata/care/examples/alicebob/example uses CARE. Here the main application is located in the file AppWithCARE.java whilst the services are under the folder principals.
The second implementation of this example src/main/java/io/github/contractautomata/care/examples/alicebob/exampleWithoutCare does not use CARE. In this case all the low-level communications between services and the orchestrator have been implemented from scratch.
These two implementations are compared to show the benefits brought by using CARE.
Using CARE, the measures are: Lines of Code = 153, Cyclomatic Complexity = 16, Cognitive Complexity = 8.
Without using CARE, the measures are: Lines of Code = 784, Cyclomatic Complexity = 134, Cognitive Complexity = 166.
This comparison has been performed using SonarCloud, and is available for inspection at:
https://sonarcloud.io/component_measures?metric=complexity&selected=contractautomataproject_CARE_Example%3Asrc%2Fmain%2Fjava%2Fio%2Fgithub%2Fcontractautomata%2Fcare%2Fexamples%2Falicebob&id=contractautomataproject_CARE_Example.
An earlier video tutorial for importing and executing the Alice and Bob example with CARE, also showing other features of CARE is available at https://youtu.be/Zq0KVUs9FqM.
An executable jar for this example is also available in this page, the next video tutorial below also shows an execution of this example.
Composition is one of the main operations performed by CATLib, and it can be a costly operation. For a front-end (e.g., CATApp) running on a standard laptop, a desirable feature could be to delegate such costly computations to a remote service, hosted on a powerful machine.
This example showcases a composition service that receives the operands automata together with other options from a client service, and computes the composed automaton. The user interacts with the client service at console to indicate which automata to compose and the various options. CATLib features an on-the-fly bounded composition. When extending the bound of a previously computed composition, the previously generated states of the composition are not recomputed. The newly generated states are only those that were exceeding the previous bound. Another scalability feature offered by CATLib is the possibility of not generating (and visiting) transitions of the composition being computed that are violating an invariant property on their labels. For example, in a composition closed under agreement all transitions that are labelled with requests are not generated (only offers and matches are present).
The sources of this example are located under the folder src/main/java/io/github/contractautomata/care/examples/compositionService/withCARE whilst the corresponding contract automata are under the folder resources/compositionService.
The example is composed of a client contract and a service contract. The client contract is displayed below, whilst the service contract is dual (all requests are turned to offers).
Note that the client contract can perform a necessary request update from state Computing. This guarantees that in a non-empty orchestration the necessary request of the client is matched by a corresponding offer. If such request would not be necessary, a non-empty orchestration could be obtained also when the client is composed with a service that does not offer the update action, but only actions create and quit.
From state Init the client can either terminate or can perform a create request.
The implementation of such request is located in the class Client.java.
When the request is executed, an object of class Payload.java is submitted to the remote service.
For creating the payload object, the client service interacts with the user at console and asks to type the needed input.
The payload contains the automata to compose, a flag indicating whether the composition is closed under agreement, and a bound on the depth of the composed automaton.
The service receives the offer and replies with the composed automaton. The implementation of the service offers are in the class Service.java.
When performing the update request, the client sends an incremented bound to the service, which proceeds to compute the composition with the extended bound and sends it to the client. The request quit is used as a signal for resetting the computed composition and the bound.
The classes ClientChoiceROC.java and ServiceChoiceROC are extending the class MajoritarianChoiceRunnableOrchestratedContract.java of CARE. In particular, these classes are overriding the method select used for selecting one of the possible choice options. Indeed, the base implementation performs a probabilistic selection using a uniform distribution and needs to be overridden by each service to implement the specific choices to be made. In this example there are two choices: in state Init the orchestration can terminate or an action create can be executed. In state Computing two possible actions can be performed. The class ServiceChoiceROC overrides the method select to always reply with an empty answer. This means that all choices are external to the service, the service does not indicate which choice has to be made. The class ClientChoiceROC overrides the method select and implements both choices as internal. The user of the client service will interact at console with the client service, and will indicate which choice has to be made.
Finally, the executable class AppComposition.java is used for testing this example.
A video tutorial is available at this link https://youtu.be/--FbqHrINek showing how to run the CompositionService example and the Alice and Bob example. The executable jars of both examples have been released in this page.
The second implementation of this example is at src/main/java/io/github/contractautomata/care/examples/compositionService/withoutCARE and it does not use CARE. In this case all the low-level communications between services and the orchestrator have been implemented from scratch.
These two implementations are compared to show the benefits brought by using CARE.
Using CARE, the measures are: Lines of Code = 279, Cyclomatic Complexity = 42, Cognitive Complexity = 55.
Without using CARE, the measures are: Lines of Code = 854, Cyclomatic Complexity = 155, Cognitive Complexity = 211.
This comparison has been performed using SonarCloud, and is available for inspection at: https://sonarcloud.io/component_measures?metric=ncloc&selected=contractautomataproject_CARE_Example%3Asrc%2Fmain%2Fjava%2Fio%2Fgithub%2Fcontractautomata%2Fcare%2Fexamples%2FcompositionService&id=contractautomataproject_CARE_Example