Installation Guide

 

Installation Guide 

JCL has two versions: multicore named Lambari and multicomputer or cluster named Pacu. First, download the binaries from JCL site and select one version to deploy. 

If you are interested in Lambari version, just import the jclUser jar file in your Java project. The jcl_binaries folder has all necessary files used to deploy Lambari version. Figure 1 illustrates a similar view of your project in Eclipse IDE. In the folder lib of Figure 1 there is the jclUser jar file. After that, you must place the folder jcl-conf in the same level of your project folder, similar to Figure 2. 

Figure 1. JCL project with examples to start developing in JCL

 

Figure 2. How to configure your project and the JCL-conf folder

 

 Finally, you need to configure the JCL config file, placed inside the JCL-conf folder. Figure 3 illustrates such a property file. Just change the property distOrParell to false to use JCL Lambari version. Now you can start developing multicore JCL applications. 

 

Figure 3. JCL property file

 Detailed explanation of each property of JCL config file:

Distorparell -  A true value indicates pacu version and the opposite a lambari version.

Servermainport - is the logical port where JCL server receives requests.  

superPeerMainPort - is the Super-Peer port that receives requests.

RouterMainPort - Port used for routing capabilities of Super-Peer.

hostport - is the Host port that receives requests.

simpleServerPort - is the User port that receives requests.

serverMainAdd - is the Server IP.

NIC - Sometimes, we work in a computer with more than one network card (NIC). In this situation, it is necessary to specify which NIC the JCL will try to get the IP. To force the JCL to get the IP from a specific NIC, the developer must define its name.

timeOut - A timeout must be defined to close some network communications among JCL User, JCL Server, JCL Super-peer and JCL Host components. It is defined 5 seconds (5000 milliseconds), so the developer can change this value.

routerLink - When a Super-peer is used, it makes some network tunnels with the Server. Using this strategy, no extra configuration is necessary, such as NAT or firewall configurations. The number of tunnels is defined in routerLink property. It is configured to have 5 tunnels, i.e. five Super-peers tunnels in a JCL cluster with the JCL Server, so the developer can increase this number. It is important to know that tunnels generate bottlenecks in the Server component, since all communications are bypassed by the Server.

enablePBA, PBAsize and delta - PBA is an optimization of JCL, where execute calls are buffered and submitted in a unique JCL message to a JCL Host. Such an optimization is very useful in JCL applications with several loops and recursive calls. Enablepba, pbasize and delta properties define PBA utilization. PBA is not enabled by default, so the developer must set to true and then change the number of task calls stored in a buffer. The value configured to buffer size is 50 task calls and delta 0.

twoStep - JCL has a scheduler implemented in two complementary phases. In the first phase, the number of tasks sent to a Host is equal to the number of cores in such a Host. In the second phase, each Host tries to help its neighbors, i.e. after the last task is completed, the scheduler tries to get a task from another Host. The second phase of JCL scheduler can be enabled or disabled by setting TwoStep property. It is configured to be true, i.e. to adopt the collaborative behavior in scheduling.

useCore - JCL is elastic, i.e. it configures its workload periodically, so if the developer decides to reduce JCL workload to 50% of a machine JCL will use 50% of number of cores threads without restarting. Usecore property is defined for such a purpose and its default value is 100% of the machine cores, i.e JCL working threads for execute tasks are equal to the number of cores.

iotUseCore -  this property defines the number threads used for IoT services, since they can work together with threads for processing and storage services.

Enabledinamicup -  this property enables JCL User component to receive control data from JCL Hosts.

findServerTimeOut, findHostTimeOut - There are two timeouts definitions to discover a Server and a Host in a JCL cluster – properties findservertimeout and findhosttimeout.

verbose - shows extra debug.

deviceID - the device name.

DeviceType - this property indicates which services will be enabled on the Host. The possible values are:

      1. Only storage service;

      2. Only processing service;

      3. Storage and processing services;

      4. Only sensing service;

      5. Sensing and storage services;

      6. Sensing and processing services;

      7. Sensing, storage and processing services;

Encryption - this property is responsible for enabling or disabling cryptography on the messages sent by the Host to other JCL components. The properties mqttBrokerAdd and mqttBrokerPort allows the user to specify a MQTT Broker to send sensing data of IoT Hosts.

mqttBrokerAdd - MQTT broker IP server.

mqttBrokerPort - MQTT broker port server. 

 

 JCL Pacu Version

 

First, download JCL binaries in JCL site. The downloaded zip file has several folders. Figure 4 illustrates such folders.

Figure 4. JCL folder

 

The jcl_binaries folder has all necessary files used to deploy Pacu version. The user first executes the JCL-server. JCL-server adopts the jcl_conf property file explained before. The developer must install only one server per cluster. JCL requires the server port configuration, so configure jcl_conf file before start JCL-Server. Basically, set the port to start listening. If you do not configure the Server port, it will adopt the default port number (6969). To run a JCL server just execute Server.bat (Windows) or Server.sh (Linux). A message “JCL Server ok!” must be printed in your prompt. Figure 5 illustrates the console message.

 

Figure 5. JCL Server message

 

After Server installation, you can run as many JCL-Hosts as you and your friends can have. Each machine must have a single JCL-Host. Copy the same downloaded zip file to each machine of your cluster.

 

Similar to JCL-Server, you can configure the JCL-Host port or adopt the default port number of config property file (5151). To run a JCL-Host, just execute Host.bat (Windows) or Host.sh (Linux). The Host will find the JCL-Server deployed in the same network, so no other configuration is necessary. If no JCL-Server was deployed, the JCL-Host will become the Server. In summary, JCL-Host will try to start the cluster anyway. A message is presented in your prompt similar to:

machine with 4 cores

JCL started - mac: E0-B9-A5-3E-8B-13

 

If the JCL-Host discover process starts and no Server is found, a message similar to Figure 6 is presented.  

Figure 6. Find JCL-server

In multi-cluster environments, there will be several machines managed by a super-peer and several super-peers managed by a server. This hierarchical structure is very useful for smart houses, universities, but also smart cities. 

To install a super-peer, you can configure the JCL-Super-Peer port or adopt the default port number of config property file (6868). To run a JCL-Super-peer, just execute Superpeer.bat (Windows) or Superpeer.sh (Linux). The Super-peer will find the JCL-Server deployed in the same network, so no other configuration is necessary. If the JCL-Server is deployed in a different network you must change de config property file manually, configuring the correct Server port and IP. Note that, you must deploy a JCL-Host or a JCL-Server before a JCL-Super-peer. After the Super-peer, you can deploy other JCL-Hosts or even other JCL-Super-peers.

 

IMPORTANT: JCL bat and sh files are used to start Server, Super-peers and Hosts. You can configure Java heap before start these JCL components. By default, JCL configures 2GB of heap for Hosts and 1GB of heap for server and super-peer. Figure 7 illustrates the bat file for Host. For instance, JCL BIG Sorting requires at least 8GB per JCL host, since it executes Terabytes of data. Raspberry Pi clusters, Edisons or cubieboard clusters, on the other hand, normally requires 128 or 256MB for Java heap. Just DO NOT FORGET TO CONFIGURE JAVA HEAP ACCORDING TO YOUR NEEDS!!

Figure 7. Configure Java heap for each cluster machine

 

 

 

JCL IoT Installation Peculiarities

 

The IoT version of JCL can be executed on boards with Linux support, Android devices and on Arduino MEGA. We show how to install the JCL-Host component on each platform.

 

Android

To install the JCL-Host on an Android device, it is necessary to install the JCL_Android.apk. The installation occur in an intuitive way, such as any other Android application. The main screen of JCL-Host is composed by three tabs as shown in Figure 8. The main tab ("Compatibility") is responsible for starting the Host and also for bringing information about the supported sensors by the device.

 

Figure 8 - Main screen of JCL-Host on Android

 

The second tab ("Sensors configuration") allows the user to enable/disable sensors though the graphic interface in runtime, i.e, without programming code. Figure 9 illustrates this tab.

 

Figure 9 - Sensor list

It is only necessary to click on the desired sensor to enable it. A screen will pop-up as shown in Figure 10 where the user must inform the interval for collect sensing data in milisseconds and also the maximum number of registers that will be stored for that sensor. Figure 11 shows the modification of the interface when the sensors are enabled.

 

Figure 10 - Enabling a sensor

 

Figure 11 - Screen after configuring a sensor

Figure 12 ilustrates the third tab ("Host configuration"). It is similar to the config.properties file existing on the Java Hosts. Through this tab, the user inform the IP address and port of the JCL Server, of the MQTT server, the nickname of the device and others. These configurations must be defined before starting the Android Host. If no valid Server is configured, JCL-Host Android will try to find a Server in the same network, identical to Java JCL-Host. The Android Host will not become a Server if no Server was deployed. Only Java Hosts perform this responsability.  

Figure 12 - Host configuration tab

 Arduino

To install the JCL-Host on an Arduino MEGA, it is necessary to install the JCL_Arduino library located in JCL site. JCL uses some external libraries for regular expression (https://github.com/nickgammon/Regexp), MQTT client (https://github.com/knolleary/pubsubclient), cryptography (https://github.com/DavyLandman/AESLib) and hash generation (https://github.com/Cathedrow/Cryptosuite). The zip file contains all these libraries and also the JCL library. The simpler way to install all necessary libraries to run JCL is to copy all the content to the libraries folder of the Arduino installation. After that, one can import the JCL library to a sketch. Figure 13 shows an example of a sketch to start the JCL-Host on the Arduino. It is important to note that it was tested using the Ethernet W5100 shield.

 

Figure 13 - Arduino sketch example

Boards with Linux support

The JCL-Host used on the boards with Linux support is the same Java Host used in traditional computers and notebooks. Therefore, the installation process is the same presented in the beggining of this guide. However, to use sensing and actuating features, JCL uses the MRAA library (https://iotdk.intel.com/docs/master/mraa/). So it is necessary to compile this library on the board to use IoT features. The manual for compiling the library can be found at https://iotdk.intel.com/docs/master/mraa/building.html. After that, before starting the Host it is necessary to indicate the path where the MRAA library was compiled in the board though the directive Djava.library.path. This can be done by openning the Host.sh file and specifying the path as in the above example:

java -Djava.library.path=/home/root/mraa/build/src/java -jar JCL_Host-1.0.jar

 

How to develop your first JCL application? The answer is on Java Cá&Lá Programming Guide, compatible with Lambari and Pacu JCL versions.