Boxes are the basic building blocks of Zaluum.
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.
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.
The data dependency between boxes must form a Direct Acyclic Graph (DAG). The execution order is a Topologic Order on this graph.
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:
byte
into an int
but not int
to byte
.
Primitive types can be boxed and unboxed before applying the above rules.
NOTE Java 5.0 generics are not yet supported.
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 boxDepending 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.
boolean |
red |
byte |
cyan |
char |
green |
short |
light blue |
int |
blue |
long |
dark blue |
float |
yellow |
double |
orange |
The Zaluum support in Eclipse is nearly transparent to the user. There are a few concepts worth knowing.
When you create a Zaluum Project the needed Zaluum Library Container is added to the classpath.
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.
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.
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.
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
|
Arithmetic operations
|
2 inputsint , 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 inputsint , long
, float or double
|
1 output The same as the input. |
Changes the sign of the input. Equivalent to multiply
by -1
|
Bitwise operations
|
2 inputsboolean , int
or long (Not has only 1 input)
|
1 outputboolean , int
or long |
Performs the operation bitwise on numeric types or applies the logic to the boolean data. |
Shift operations
|
2 inputs toShift: int or long shift distance: int
|
1 outputint or long |
Shift and rotates like shift operators in Java TODO link |
Equality testing
|
2 inputs Any type |
1 outputboolean |
Compares two primitives, or two objects for equality (by reference) TODO |
Numeric comparison
|
2 inputs Any primitive numeric type. |
1 outputboolean |
Performs the comparison and returns the result. |
Name | Inputs | Outputs | Description |
---|---|---|---|
While box![]() |
|
|
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![]() |
|
|
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 operate with object oriented logic, similar to the same concepts in Java.
Name | Inputs | Outputs | Parameters | Description |
---|---|---|---|---|
Box instance |
|
|
|
This box type creates an instance of a class box. It does it in a series of steps:
The behavior of the box is determined by the properties
The inputs will be:
The outputs will be:
This box type is likely to change
before v1.0
|
This reference | None |
|
None | ADVANCED
Returns the current instance of the class in which it appears.
Like the Java
|
Type cast |
|
|
|
Converts one type into another. The rules are the same as Java. |
Method invocation |
|
|
#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
The objectIn reference is copied to objectOut |
Static method invocation |
|
|
|
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 |
|
|
#Field The name of the accessed field. |
If the input is wired, it sets the field named
The objectIn reference is copied to objectOut |
Static field access |
|
|
|
If the input is wired, it sets the static field named
|
New object |
|
|
|
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 |
|
|
Accesses the array at index index. If the input is wired it sets its value. | |
Array compose |
|
|
|
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) |
|
|
Creates an array of type
For example
|
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.
The Zaluum palette is composed of:
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:
#Class
set to the Zaluum file, so you
can instantiate Zaluum boxes easily.
@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
.
@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.
/META-INF/zaluum.xml
. This
file may contain additional template entries and is described in
section XXX.
The icon shown for a box in the diagram view and in the palette is determined in the following order:
META-INF/zaluum.xml
file exists for the box, it's chosen. See XXX.
.png
extension, in the same
package and with the same name of the box meant to override is
present, it's chosen.
package.png
in the package directory.
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
.
A Zaluum file, viewed from Java, is equivalent to the following:
run
"
if no output port is present.
void
if none is present.
#Class
with field name *Name
.
XXX
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.