Send Multiple Emails Tutorial

Summary. The purpose of this tutorial is to show that we can utilize block contracts when composing rather complex building blocks (e.g., have many pins). In particular, we show that we do not need to see the inner details of those blocks. Moreover, we also learn how to fix errors in the specification

Step 1: Install the Reactive Blocks SDK

Step 2: Import and Open the Tutorial Project

  • Start the import wizard, as explained here. Import the following project:
    • (Level 2)Multiple Emails (start here)

Note that there is a similar project called (Level 2) Multiple Emails (finished) containing a complete and correct system specification.

  • Open block Send Multiple Emails in the tutorial project.

This application block already contains three building blocks, namely:

  • Emails Generator
  • Buffer Eager Simple
  • Send Email

With these blocks we will build an application that sends multiple emails which are generated at random time intervals by block Emails Generator. Block Send Email can only send one email at a time. Hence, there is a possibility that there are many emails generated while an email is being sent. In order to avoid losing emails, we buffer them by using block Buffer Eager Simple.

Step 3: Connect Blocks and Operations

Let us now connect the building blocks to make a complete application. Connect the system as shown below:

Some additional details:

  • The operation init configures the gmail account you are going to use, namely username & password. Double click it to edit the Java code appropriately.
  • The variable temp is used in operation error to generate a proper error message.
  • If the buffer contains no more emails, Buffer Eager Simple will emit an event through pin empty. However, this pin is not connected to any other nodes as the application can simply wait for other generated emails. The application will run until it is forced to stop.
  • Once you are done, you might want to delete the TODO comments as they are not longer needed.

Step 4: Analyze

Now, let us analyze the application block. Choose Analyze from the context menu of the application block.

Analysis view will pop up showing the result as depicted below.

We see that block Send Multiple Emails has an error, namely Flows harms the contract of block 'Send Email'. Lets now try to understand it & fix the problem.

Get the detailed description

A detailed description about an issue is given by clicking the issue. For the error shown in the figure above:

  • It seems that there is an activity step that violates block Send Email.
  • The harming step is trigger by transition /failed from the violated block and traverses pins failedsend.
  • Note, that you may get the same issue with pin ok instead of failed. In case there are several equivalent issues, their order is nondeterministic. However, in our case the possible reported errors are just two variants of the same issue.

Each type of detected issues is explained in our website together with examples and possible fixes. An overview of all issues are shown in this gallery. To go directly to a type of issue you encounter, just click link Read more about this issue… (scroll to find it) in the Analysis view, or click here for our current error.

Hightlight the situation

You may want to Highlight the situation by clicking it in the detailed description of the error:

This action will accentuate block SendEmail and the harming activity step:

Have a look at the involved block contract

Exit the highlighting by pressing the ‘x’ key. Open the contract of block Send Email choosing Show Contract from the block's context menu (right-click the block):

It shows that the block SendEmail is activated via pin send going from its initial state to state active. From state active two transition are possible reporting the two possible outcomes, namely ok or failed, going to state final. There is no transition that includes both pins send and failed.

Use Animation

To further understand that such a step may occur, you can use the action Start animation towards the situation by clicking this action in the detailed description of the error. (It might be helpful to also open the contracts of the inner blocks.) Some parts of the model are highlighted as shown in the following figure.

You can use arrows → and ← to run through the three steps leading to the error condition.

  • Activity step 1: block Emails Generator is initialized. It, then, arrives in state active.
  • Activity step 2: block Emails Generator emits an event via pin email which is received by block Buffer Eager Simple via pin add. Buffer Eager Simple is going to state firstItemAdded.
  • Activity step 3: Buffer Eager Simple emits the first item via pin out. Further, the email is received by block Send Email via pin send. This step changes the state of block Buffer Eager Simple to active and block Send Email to active.
  • Activity step 4: block Send Email emits a token via pin failed which is forwarded through operation failed, the merge node, pins next and out of block Buffer Eager Simple, and pin send of the send email block. This is the activity step also shown when using Highlight the situation as done above.

The last activity step harms block Send Email as there is no transition that involves both pins failed and send. The behaviour of application block Send Multiple Emails is not compatible with the contract of block Send Email.

Step 5: Fix the Error

Note that the contract of block Send Email allows transition labelled with /failed to a final state. Moreover, it also allows transitions send/ from an initial state to state active. This means that we try to restart the block Send Email within one activity step which is forbidden by its contract.

As also described here, there are basically two alternatives to fix the error. However, since we can't modify the inner block's contract (as it is taken from a library), we correct the error by splitting the activity step 4 (see above) into two activity steps:

  • Exit the animation mode by selecting Exit Animation from the application block's context menu. Press x if the black bar on the bottom won't go away.
  • Add a flow break (0ms timer) between the merge node and pin next of block Buffer Eager Simple. This will split up the harming activity step into 2 activity steps.

After having fixed the issue:

  • Analyze the application block again. You should find no error.
  • Use the animation to be able to see the additional activity step.

You can build and run the application if you wish. However, remember to set the username and password variables in the operation init with your gmail or google account and password respectively.