User guide

Work in progress... To introduce Zaluum at this Preview stage, it will be assumed that you have a basic knowledge of Java. Please refer to the java tutorial, to refresh the basic concepts.

About boxes

Boxes are the basic building blocks of Zaluum.

Box anatomy

Boxes represent operations on data. They operate on the data arriving by the wires attached to them. The points where you can attach a wire to a box are called ports.

Ports at the left side of a box are input ports. Ports at the right side, output ports. A box performs some operation to the inputs and, optionally, its internal state to produce one or more outputs.

Composite boxes can make use of the shift ports. A Shift port holds the last value it's been written and can be read and written multiple times from inside the box they are assigned.

Shift ports are showed as a port connection in both sides of the composite box. Each port connection has one terminal inside the box and another one outside. So each shift port has a total of 4 terminals.

When a composite box starts to execute, the initial value of the shift port is taken from the outside terminal of the left connection, like an input port. On each iteration, the port value is updated with the inside connection at the right side. Finally the other boxes can read the value set in the last iteration on the right terminal of the right connection.

Some boxes

Execution order

The execution order of the boxes is calculated by the platform based on the rule that a box can only be executed when all the boxes that provide its inputs have already been executed. This means that no cycles can be present in a Zaluum diagram, since no solution could be found.

The execution order of two boxes with no data dependency is undefined and can potentially be executed in parallel.

PRO

The data dependency between boxes must form a Direct Acyclic Graph (DAG). The execution order is a Topologic Order on this graph.

Wires and data types

Each port has a definite data type. The types in Zaluum are the types available in Java: Class (or interface), Array or primitive type.

You can connect an output port to multiple inputs but an input can only have one connection. An unconnected input defaults to 0 or null .

You can create connections between an input and an output only if they have compatible types. Type compatibility follows the rules of java for type conversion and promotion, detailed in the Java Language Specification . In summary two types are compatible if:

They are the same
They are primitive type and you can convert the source type into the target type with no loss. A byte into an int but not int to byte.
The source type is a subclass or implements the interface of the target type.

Primitive types can be boxed and unboxed before applying the above rules.

NOTE Java 5.0 generics are not yet supported.

Box properties

Inputs and outputs apart, boxes have also properties.

There are 3 properties shared across all types of boxes

*Name An unique name in the class. Must be a valid Java identifier (start with letter, no spaces, no symbols)
*Label An optional string that is shown in the diagram next to the box
*GUI Label An optional string shown in the GUI next to the widget
*Type The type of the box

Depending on the type of the box, there can be more properties added to box. Please refer to the box types guide.

Finally, the box instance type adds the JavaBeans properties of the class of the box.

Classes and packages

TIP

Each type has a color and line style in Zaluum, the Java primitive types are:

`boolean`	red
`byte`	cyan
`char`	green
`short`	light blue
`int`	blue
`long`	dark blue
`float`	yellow
`double`	orange

About Eclipse

The Zaluum support in Eclipse is nearly transparent to the user. There are a few concepts worth knowing.

Zaluum projects

The Zaluum source files must reside in source folder of an Eclipse project with both Java nature and Zaluum nature enabled. This is a Zaluum Project. You can create a Zaluum project by:

Creating a Zaluum Project with File→New→Zaluum Project
Adding the Zaluum Nature to a Java Project. Right click on the project Configure→Convert to Zaluum Project

When you create a Zaluum Project the needed Zaluum Library Container is added to the classpath.

Views and perspectives

When you switch to a Zaluum Project, the Zaluum Perspective is automatically enabled. It contains the Zaluum Properties view and the Zaluum Palette view. The Zaluum Properties view is required to edit Zaluum files, but the palette can also be reached by right-clicking a blank space in an open Zaluum File.

NOTE It is very useful to have the Problems view in sight while editing Zaluum Files. You can double click the error to go to the source of the problem.

Running a Zaluum Project

You can run a Zaluum file in a simple runtime framework selecting the desired main Zaluum class, right clicking and select Run as...→Zaluum Application. Note that to launch a Zaluum file in this mode it cannot contain any input ports.

As Zaluum projects are Java projects, so you can create a class with a main and call the Zaluum files from there.

GUI editor

Zaluum can also create a graphical interface for your box. Press F6 or the GUI button on the toolbar to open it. The GUI editor changes the setBounds property of the boxes inside.

TIP

If you remove the Zaluum Library Container by accident, you can reenable it doing the following: Right click on the project Build Path→Add Libraries and select Zaluum Library Container

NOTE When you create a Zaluum project, the required classpath libraries are set up automatically, so you don't need to worry about this.

TIP

Compilation is done automatically if Project→Build automatically is checked.

PREVIEW

Refactorings are not yet implemented, and some functions of Eclipse Java support may not work in the presence of Zaluum files.

Basic boxes

They can be found in the org.zaluum.op package of the palette.

Name	Inputs	Outputs	Description
Literal expression	0 inputs	1 output The narrowest type that can hold the parsed data.	Creates values from a string. Use it to insert constant numbers or strings into your dataflow. The property `literal` is parsed and converted it into a value with the following rules: `true` and `false` are converted to `boolean` If the literal ends with the letter `f` or `F` it's converted to a `float` If the literal ends with the letter `l` or `L` it's converted to a `long` If the literal starts and ends with double quotes `"` its converted to a `String` (double quotes not included) Else it's parsed as an integer. The type is the smallest that can hold the value: `byte`,`short` or `int` If failed to parse as an integer. It's parsed like a `double`. Finally if all fails, it's interpreted as a `String`
Arithmetic operations Sum Substraction Multiplication Division Remainder	2 inputs `int` , `long` , `float` or `double`	1 output Its type is the wider type of the two inputs.	Perform numeric operations on incoming data. You can operate with smaller primitive types `byte` or `char` with the automatic cast to `int`.
Minus	1 inputs `int` , `long` , `float` or `double`	1 output The same as the input.	Changes the sign of the input. Equivalent to multiply by `-1`
Bitwise operations And Or Xor Not	2 inputs `boolean`, `int` or `long` (Not has only 1 input)	1 output `boolean`, `int` or `long`	Performs the operation bitwise on numeric types or applies the logic to the boolean data.
Shift operations Shift left Shift right Unsigned rotate right	2 inputs toShift: `int` or `long` shift distance: `int`	1 output `int` or `long`	Shift and rotates like shift operators in Java TODO link
Equality testing Equals Not equals	2 inputs Any type	1 output `boolean`	Compares two primitives, or two objects for equality (by reference) TODO
Numeric comparison Less than `Lt` < Less or equal than `Le` ≤ Greater than `Gt` > Greater or equal than `Ge` ≥	2 inputs Any primitive numeric type.	1 output `boolean`	Performs the comparison and returns the result.

Composite boxes

Name	Inputs	Outputs	Description
While box	N user ports: input or shift	1 boolean condition output. If true the body is executed again. N user ports: output or shift	Executes the inner boxes in their order one time. If the cond port is true, they are executed again, with the values of the shift ports assigned in the last iteration.
If box	1 boolean condition port N user ports	N user ports	If box has two pages, and each one can contain inner boxes. Page selected as T by switch is executed if the cond port is true, the F page if false.

Object boxes

Object boxes operate with object oriented logic, similar to the same concepts in Java.

Name	Inputs	Outputs	Parameters	Description
Box instance	N inputs. The number an type of the parameters of the selected `#Method`	Zero or one. The return value of the selected `#Method` N outputs. The selected `#Fields` or the fields annotated with `@org.zaluum.annotation.Out`	`#Class` The name of the class to create `#Method` The name and arity of candidate methods `#Fields` The names of the fields to be added as outputs `#Constructor types` The types of the parameters of the constructor to be used `#Constructor values` The values of the parameters of the constructor `#Script` An optional JavaScript to be executed after the object creation N properties. All the JavaBean properties of the class defined with a getter and setter method with a type that can be parsed as a literal.	This box type creates an instance of a class box. It does it in a series of steps: Creates an instance of the class `Class` using the constructor that matches the arity (number of parameters) and types of `#Constructor types` . To invoke the constructor it parses the values `#Constructor values` using the `#Constructor types` If no constructor is specified it uses the public default constructor (public with no parameters). and stores it in an internal field. It uses the constructor The newly created box is stored in an internal field of the class being defined. After the creation of the object, the contents of `#Script` are evaluated as `JavaScript`. This can be useful for some widget setup tools to configure the recently created object. The behavior of the box is determined by the properties `#Method` and `#Fields` . `#Method` chooses the name and arity of the candidate methods to be invoked. The actual method invoked will be determined among the overloaded methods by the compatibility of the incoming wires. If no `#Method` is specified, the ones with an `@Apply` annotation are selected as candidates. The inputs will be: The parameters of the choosen method. The outputs will be: One or zero ports: The return value of the method invocation. Zero if void Plus Zero or more: The values of the `#Fields` after the method invocation. This box type is likely to change before v1.0
This reference	None	1 output. The `this` reference. The type is the class in which this box is instanced.	None	ADVANCED Returns the current instance of the class in which it appears. Like the Java `this` .
Type cast	objectIn an object or primitive value. Any type.	objectOut The value objectIn casted to type `#Class`	`#Class` The class or primitive type to cast to.	Converts one type into another. The rules are the same as Java.
Method invocation	objectIn: The object on which invoke the method N ports: The parameters of the method to be invoked on objectIn	objectOut The same object as objectIn. (For chaining) Zero or One: The return value of the method. (Zero if void)	`#Method` The name and arity of the method to be invoked on the object objectIn	Invokes the method that matches the name and arity of `#Method` and the types of the incoming wires to the N input ports. The result of the invocation is put on the output The objectIn reference is copied to objectOut
Static method invocation	N inputs. The parameters of the static method invoked.	0 or 1 outputs. The result of the invocation	`#Class` The class containing the static method `#Method` The name and arity of the method to be invoked	Invokes the static method on the `#Class` that matches the name and arity of `#Method` and the types of the incoming wires to the N input ports. The result of the invocation is put on the output.
Field access	objectIn The object having the field. 1 input - If wired it sets the value of the field.	objectOut The objectIn reference 1 output - The value of the field	`#Field` The name of the accessed field.	If the input is wired, it sets the field named `#Field` of objectIn to the incoming value. The output is the value of the field. The objectIn reference is copied to objectOut
Static field access	1 input. If wired it sets the value of the field.	0 or 1 outputs. The value of the field	`#Class` The class containing the static field `#Field` The name of the static field accessed.	If the input is wired, it sets the static field named `#Field` of the class `#Class` to the incoming value. The output is the value of the static field.
New object	N inputs. The constructor parameters	1 output. The new object of type `#Class`	`#Class` The class to be instanced. `#Constructor` The arity of the constructor	Creates a new object using a constructor matching the arity of `#Constructor` and the parameter types of the incoming wires. The result is a new object of class `#Class`.
Array access	objectIn The array being accessed index an `int` representing the 0-based index to access One input. If wired it sets the value of the array at index index	objectOut The array objectIn one output. The value of the array at index index		Accesses the array at index index. If the input is wired it sets its value.
Array compose	`#Size` number of inputs of type `#Class`.	1 output. The created array of type `#Class` and length `#Size`.	`#Class` the class or primitive type of the array being created `#Size` the number of inputs (size of the array)	Creates a new array of type `#Class` and size `#Size`. The values of the array are those wired to each position.
New array	`#Array Dimensions` number of inputs representing the size of each dimension (`int`s)	array The newly created array.	`#Class` The type of the array. `#Array Dimensions` The number of dimensions of the array	Creates an array of type `#Class` of `#Array Dimensions` . The size of each dimension is assigned by the inputs. For example `#Array Dimensions` =2 and `#Class` = `int` would be equivalent to the Java code: `new int[a][b]();` . Being a and b the input ports.

Using Java from Zaluum

Method overloading

There are some box types that require you to specify a method to invoke in their properties. In Java, a method name can be overloaded: methods can share name in the same class as long as they have different signatures i.e. have distinguishable parameters, by type and/or by number(arity).

For example:

class Foo {
	public void bar(int a, int b) {
		return;
	}
	public long bar(int a, long b) {
		return a-b;
	}
	public int bar() {
		return 0;
	}
}

When a box requires a method, you need to specify a name and the number of parameters taken (arity). In the example if we select name bar with arity 2, the box will show 2 input ports. The method to be called (int,int) or (int,long) will depend on the wires we connect to its inputs. If we connect two ints, the first will be called; if we connect (int,long), the second. There will not be an output port in the first case, and a long one will appear in the second.

Zaluum matches the best method to call according the Java rules of method invocation. If there is any ambiguity an error is shown. In the example, if no input is connected the method to invoke is ambigous, and an error is shown.

TIP Because of method overloading, some boxes can change its outputs when connected, depending on the type of the wires we attach to it.

The palette

The Zaluum palette is composed of:

Tools to create ports
Simple Zaluum box types
Templates

The simple Zaluum box types are the basic building blocks of all Zaluum files, and all the simple types are listed in the section Types of boxes. They are equivalent to the basic syntax of a textual language.

The Templates are simple Zaluum box types with some properties pre-set. They are useful because they let you add boxes faster. Template entries to the palette come from the following sources:

Every Zaluum file creates a Template of Box Instance with #Class set to the Zaluum file, so you can instantiate Zaluum boxes easily.
Java classes annotated with @org.zaluum.annotation.Box create a Template of Box Instance with #Class set to the Java class. You can instantiate Java classes easily if they have been annotated with Box.
Java public static methods annotated with @org.zaluum.annotation.Box, that reside in any Java class annotated with @org.zaluum.annotation.StaticBox create a Template of Static Method Invocation with #Class set to the enclosing class and #Method selecting the annotated method. This way you can turn static methods into boxes easily.
All the classpath roots (your source and library jars) are scanned for the file /META-INF/zaluum.xml. This file may contain additional template entries and is described in section XXX.

Icons

The icon shown for a box in the diagram view and in the palette is determined in the following order:

If an image override in a META-INF/zaluum.xml file exists for the box, it's chosen. See XXX.
If a file with .png extension, in the same package and with the same name of the box meant to override is present, it's chosen.
A fallback icon is generated with the name of the class.

An icon for a package can also be defined by putting a package.png in the package directory.

Swing widgets

When using a Box Instance with a Java class, if this Java class extends java.awt.Component , the box is considered visual and the widget is shown in the GUI view. The position and size assigned to the widget to the setBounds method of java.awt.Component .

Zaluum from Java

Java view of Zaluum file

A Zaluum file, viewed from Java, is equivalent to the following:

A public class named as the file (without the .zaluum) in the package XXX.
The class contains a public execution method that runs the dataflow:
- The name of the execution method is the name of the first output port in lexicographic ordering or "run" if no output port is present.
- The return value of the method is the value of this same port, or void if none is present.
- The parameters of the method are the input ports of the Zaluum file in lexicographic ordering.
- For the second and following output ports, a public field with matching type and name is generated for each one. After the invocation of the execution method the values are updated with the results of the computation.
- The boxes of type Box Instance, are stored as a public field of type #Class with field name *Name. XXX
If the Zaluum file is visual (contains a visual widget), the class extends javax.swing.JFrame. The property getPreferredSize() is set to the size of the canvas of the GUI view and the widgets are added to it with a null LayoutManager, each with the getBounds() property set.

To be documented

Annotations and palette.xml
Zaluum Constructor and Initialization
Configuration wizards
Port naming internals
Scripting
Javadoc integration
Building with ant