Creating Multi-Session Blocks

What Should Each Instance Represent?

When creating a multi-session block, you need to think first what each instance of the block should represent. For instance, if the multi-session block should keep track of orders that are delivered by a fleet of vehicles, each instance can represent a separate vehicle. But that is not the only possibility. Depending on the application, instances could also represent an order number, or a driver. (Of course, you can also make a system that contains three multi-session blocks, one for the vehicles, one for the driver, one for each order handled by the system.)

Internal Behavior of a Multi-Session

All session instances run independently of each other. When creating the internals of a multi-session block, you simply build a block that as if it existed only once. The internal logic of the multi-session block can be constructed like any other building block. It can contain any other type of building block that can be part of blocks, or even other multi-session blocks.

Declaring a Multi-Session

Go to the Overview page of the editor, and select multi-session from the session combobox. This enables further syntactic checks for multi-sessions, and also tells all users of your block that it is intended to be used as a multi-session.

Aliases for Instances

Once it is clear what exactly an instance represents, you need to determine how the session instances should be distinguished from each other. For a fleet of vehicles, we can take for example the license plate number of each vehicle. Other good examples are email-addresses, order numbers, phone numbers, or MAC addresses. We call these identifiers aliases. (In principle, an alias is like a unique ID for each session instance. However, we call them aliases, since the same alias may be used in the system by different multi-instance blocks.)

Usually it is not too hard to find sensible aliases, since in most cases, the things to distinguish already have some identifier. Of course, while an instance is active, its alias cannot be changed. If you think that you need to change an alias of a session while it is active, it is most likely that you should choose some other data as alias instead.

Selection of Instances

As the only difference to normal blocks, we must describe what instances should receive a parameter. This means that when a parameter enters a multi-session block, we need to know which of the instances should receive a copy of the parameter. This can be one single instance, all instances, or just some selected ones. Depending on the type of input parameter, there are several possibilities:

  • starting parameter (to one): A multi-session block needs at least one starting parameter. This parameter creates a new session instance of the block, and therefore only targets one single session. The starting parameter must also provide the alias for the session, explained below.

  • streaming input parameter (to one) Only a single session instance will receive this parameter. Which instance that is, is determined by the incoming data type that is mapped to the alias, explained below.

  • streaming input pin (to all) This selection option makes that all running sessions receive the parameter.

  • streaming input pin (to some) To select some of the sessions, the multi-session block must implement a specific match method, further explained below.

Declaring the Selection Modus (one, some, or all)

Right-click on the parameter node and choose the selection mode.

Sending “to one” with an alias:

This holds both for starting parameters and for streaming parameters.

Whenever a parameter should target exactly one session, this parameter must be typed, and the type must somehow contain the alias. Since we need to pass more data into the block than just its alias, you need to declare how the alias can be extracted from an incoming parameter type. The block must therefore declare the following static method:

public static String getAlias( ...  ) {
...
}

The argument of this method must have the same type as the type of the incoming parameter. For instance, if the incoming parameter is of type DispatchOrder, then the getAlias method looks like this:

public static String getAlias(DispatchOrder order) {
	return order.getAssignedVehicle();
}

Sending “to some” with a match method

Sending to several session instances simultaneously can be done using a match method. The block simply declares the following method:

public boolean match(String parameterName, Object data) {
...
}

The parameter name is the name of the parameter for which the selection is called, and data is the provided input type. Based on this data, the name of the incoming parameter and any other value within the block, the session selection can be done. If the instance should receive an input, return true. In case the input parameter node is not typed, the data attribute is null.