Example: How to Create a Block Contract for Composed Blocks

When creating the contract for a block including one or more inner building blocks, the outer block contract has to take into account the block contracts of the inner blocks. As described here it is important to identify possible activity steps and those depent on the contracts of the inner blocks.

Let’s have a look at an example. Say, you have found or created a block for speech synthesis, which you want to use:

The blocks contract looks like this:

From the contract you can see that this block can handle only one string at a time. Another string can be processed once the previous string is processed (indicated either via pin finished or via pin failed). This may be a bit tricky to handle within your application, so let’s make a buffered version of this block called Speech Buffered. This composed block uses block Speech and block Buffer Eager Simple as inner blocks:

In addition to the activity for Speech Buffered as shown above, the block also needs a contract. To be able to define this contract, it is necessary to know the block contracts of all inner blocks. This is what the block contract of Buffer Eager Simple looks like:

Pin init is the only initial pin of Speech Buffered and triggeres an activity step involving the inner block Speech either with transition init/ready:

or with transition init/initiFailed:

So block Speech Buffered needs a transition init/ready (from state initial to - for example - state active) and a transition init/initFailed (from state initial to state final).

Block Buffer Eager Simple accepts input at any time via transition add/, so block Speech Buffered will have a transition add/ in state active:

Buffer Eager Simple emits items via pin out either spontanious with transition /out or on request with transition next/out. As long as there are items in the buffer which are processed by Speech successively, the related activity steps are taking place inside block Speech Buffered and won’t result in any further transitions for block Spreech Buffered. However, once all items have been processed, Buffer Eager Simple will give notice via transition next/empty. Due to the edge between empty and done this activity step affects the contract of Speech Buffered with transition /done. There are 2 activity steps resulting in the same transition for the outer block:

Finally, another activity step can be triggered via pin stop involving block Speech with transition stop/stopped resulting in transition stop/stopped for Speech Buffered:

The identified transitions are added to the tabular in the Contract tab of block Speech Buffered to define its block contract:

As diagram the contract for block Speech Buffered looks like this:

When developing the contract of a block, there are some degrees of freedom. It is for example up to you to call state active instead working. However, the analysis tool will check if the the contract is consistent with the contracts of enclosed blocks as well as with the defined behaviour given by the activity diagram.

Block Speech and block Speech Buffered are part of the Speech library and are used here as an example.