Creating Building Block

All building blocks are stored in Eclipse project. Therefore, you need to create a project before creating a block.

Create a New Project

There are several ways to start the new project wizard:

  • Use the new project icon

  • Select File → New → Other… from the Eclipse menu (or its short-cut key Ctrl+N or Cmd+N) and choose Reactive Blocks → Reactive Blocks Project

  • In a blank workspace you will also see a Create a new project… link

  • In a non blank workspace, do a right-click on the Blocks view and select New Reactive Blocks Project…

  • In a non blank workspace, do a right-click on a project or library and select New → Reactive Blocks Project…

The new project wizard looks like the following figure. You need to:

  • Fill in a full-qualified project name, e.g., org.reactiveblocks.test
  • Select a suitable project setup (see below)

Project Setup

Depending on what Reactive Blocks features installed, you may see different project setups. There are currently four available setups:

  • Application Project, Java SE

    Typically application project contains one or more application blocks. It can, of course, contain other types of block. Application blocks in this type of project will be built as Java SE executable code.

  • Library Project, Java SE

    Library project contains blocks for reuse. It usually does not contain application blocks. The difference between library and application projects is not so important as you can later switch between these two setups later.

  • JUnit Testing Project

    JUnit Testing project contains JUnit API in the classpath of the project. It usually contains test cases for blocks in other libraries/projects.

  • Plug-in Project, OSGi

    You will get this setup only if you install additional Reactive Blocks features, i.e., ESF/Kura/OSGi. This setup will create a project for an OSGi bundle. Note that this type of project can only contain maximum one application block.

Create a Block

You can create a building block as a copy of an existing block or from scratch.

To duplicate an existing block, see here.

To create a new block, start the new building block wizard. There are several ways:

  • Use the new block icon

  • Select File → New → Other… from the Eclipse menu (or its short-cut key Ctrl+N or Cmd+N) and choose Reactive Blocks → Reactive Block

  • A Create a new block… link in an existing project.

  • Do a right-click on a project and select New → Reactive Block…

The new building block wizard looks like the following figure. You need to:

  • Fill in a block name, e.g., IoT Greenhouse
  • Select a template/type
  • If you haven’t done so, select in which project the new block will be placed

Types of building block are described here.

If you install Reactive Blocks for Kura or ESF features, you will get more building block templates. These are application blocks with additional file that is related to Kura/ESF configuration feature.

After finishing the wizard, the building block is opened in the Blocks Editor. Depending on the type of building block, you see different pages in the Editor and can do different actions.

The Blocks editor for application, activity (building blocks), and shallow blocks are described below. For other block types, follow these links: state machine block, singleton blocks, multi-sessions block.

Blocks Editor - Application

An application block specifies an application at the highest decomposition level. This type of block has:

  • an activity diagram describing the behavior of the application
  • Java code containing the details of operations in the activity diagram

The Blocks editor for an application block looks like the following.

As you can see at the bottom left, there are three pages: Behavior, Overview and Documentation.

Activity Diagram

The Behavior page contains the activity diagram. It usually contains other blocks and activity nodes connected with flows. Each activity diagram in an application block has intial nodes () and activity final nodes () indicating the start and termination of the application. An application block does not have input nor output pins.

On the Behavior page you can:

  • use other blocks from imported libraries or projects
  • add and modify activity nodes
  • connect activity nodes and blocks with flows
  • start the analysis tool to find potential issues
  • start the animation tool to understand help understanding the behavior of the block
  • build, i.e., generate executable code from the application block

Note that in a read-only mode some actions are disabled. Changes to the block done during this mode are ignored (cannot be saved).

Java Code

Java code is not included in the Blocks editor. To open it in the Java editor:

  • double click an operation, e.g., getReady from the above figure
  • do a right-click on an operation and choose Go Into
  • do a right-click and choose Edit Java Code

The figure below shows the Java code of the block shown in the previous figure.

The Java class of an application block is always called Component.java. It contains methods that can be called from operations in the activity diagram.

Block Documentation

Every block has Overview and Documentation pages. These pages contain description, block status and additional resources for the block like external Java libraries. Those pages make up the content when you see the information of a block. So, to inform other developers who use your block, fill in those two pages.

Blocks Editor - Activity

When you choose Building Block as the type of the block, you will get an activity block. This type of block is intended to be (re)used or instantiated within other building blocks or application blocks. This type of block has:

  • an activity diagram describing the behavior of the application
  • Java code containing the details of operations in the activity diagram
  • a block contract describing in which order the input and output pins of a block can be used

The Blocks editor for this type block looks like the following.

As you can see at the bottom left, there are four pages: Behavior, Contract, Overview, and Documentation

Activity Diagram

Like application blocks, the Behavior page of an activity block contains an activity diagram. In contrast to application blocks, an activity block does not have initial nor activity final nodes. It has input ( ) and output ( ) pins. When the block is instantiated, the pins are used to wire the block with other blocks or activity nodes.

A pin can be typed. For example, pin init in the above figure is typed String. It means that the pin can be connected with an object flow which carries data of type String. You can add type to a pin by choosing Data type from the context menu of the pin.

On the Behavior page, you can do all actions for application blocks, except build.

Java Code

Similar to application blocks, this block type also has Java code for detailing the operation nodes. However, the Java class of this type of block is the Block name without spaces. For the Photo block above, the Java class name is Photo.java.

Block Contract

Block contract shows how the block can be used without looking and understanding the internal behavior, i.e., its activity diagram. The contract is described in tabular form on the Contract page.

On the Contract page you can:

  • add or modify a transition/state
  • invoke an action to view block contract diagram (see the following figure) by selecting Open Diagram from the context menu

Block Documentation

Like any type of block, block documentation is provided from the Overview and Documentation pages.

Blocks Editor - Shallow

A shallow block is used to coordinate flows in an activity diagram using only block contract and no internal activity. This type of block only has:

  • a block contract describing in which order the input and output pins of a block can be used

The Blocks editor for this type block looks like the following.

As you can see at the bottom left, there are four pages: Pins, Contract, Overview, and Documentation

The Pins page contains a list of input ( ) and output ( ) pins for the block.

On the Pins page, you can add or modify pins.

Block Contract

The contract of a shallow block is shown on the Contract page. See also here.

Block Documentation

Like any type of block, block documentation is provided from the Overview and Documentation pages.