API Overview

Our goal is simply to execute a task of firing a list of uniform or non-uniform HTTP(S)/TCP/UDP/SSH/PING requests to a list of target hosts (or a single target host), then call the user defined handler to handle each of the responses. We define such a task with its metadata as ParallelTask.

Let's review the sample example again for a HTTP POST call to 2 target hosts. ParallelClient is the starting point of parallec, which returns a ParallelTaskBuilder by a prepare*() function (e.g. prepareHttpGet(), prepareHttpPost(), prepareSsh(), preparePing() etc). The ParallelTaskBuilder is to build a specific ParallelTask with certain metadata. Note that the pc.releaseExternalResources() does not need to be called if using Parallec.io in a web server. It only needs until

ParallelClient pc = new ParallelClient(); 
pc.prepareHttpPost("/executeCmds")
.setHttpHeaders(new ParallecHeader().addPair("content-type", "application/json"))
.setHttpPort(10050)
.setConcurrency(1000)
.setHttpEntityBody( "{  \"cmd\":\"  df -h; \"}")
.setTargetHostsFromString("server1.host.com server2.host.com")
.execute( new ParallecResponseHandler() {
    @Override
    public void onCompleted(ResponseOnSingleTask res,
            Map<String, Object> responseContext) {
        System.out.println( res.toString() );  }
});
pc.releaseExternalResources();

Please first review these Key Classes below. We then break down on each component of a "ParallelTask", and give more details of the functions in "ParallelTaskBuilder".

These APIs can be generally categorized by the following:

• Generate and submit Parallel Task (with class ParallelClient & ParallelTaskBuilder) :
  1. APIs to set general ParalleTask attributes such as concurrency, whether to enable scheduler, whether to save response/logs, configs to set actor timeouts.
  2. APIs to set protocol specific metadata on each protocol of HTTP/TCP/SSH/Ping. Such as Http port, URL, entity body. These parameters are used by the loaded async http client.
  3. APIs to set target hosts from different sources.
  4. APIs relate to the response handling: set response handler with context, when to call the handler, whether to save responses, and whether to auto write task execution logs.
• Track ParallelTask status/results and examine responses (with class ParallelTask)

The above two part are listed as separate sections in this documentation.

Please also review Parallec Samples of list of independent examples to get single executable for parallel executions on each protocol.

Supported Protocols

Parallec currently supports the following protocols.

Function	Based Upon
HTTP	Async HTTP Client
SSH	JSch
PING	JDK net / Process
TCP	Netty
UDP	Netty

When to Release Resources

As mentioned in the javadoc, these resources (e.g. akka system, async http client store, thread pool for SSH/TCP) are Singleton. There is no need to call the releaseExternalResources() until you stop using Parallec. If you are on some web server (such as Tomcat) and runs parallec jobs as cron jobs, you will not need to call this line at all. We have several production application that runs as web server. We do not call it in our app. The actor system and the threadpools are live so that it will keep reusing the same one. If you have called releaseExternalResources(), the next time it will need to be reinitialized.

Key Classes and Notations

First let's review some key class in parallec. You may click the link to read more on their javadocs

Notations	Details
ParallelClient	This is the starting point of parallec, which returns a ParallelTaskBuilder after a prepare*() function. The ParallelTaskBuilder is to build a specific ParallelTask
ParallelTask	The key class represents a onetime execution on multiple requests. It contains all the task and request metadata, target hosts, configs, and the responses.
ParallelTaskBuilder	The key builder to build the parallel task and then execute it after the validation process. During the validation, certain missing parameters will use the default values.
ParallelTaskManager	The class to manage the current running tasks and wait queue (Singleton). generateUpdateExecuteTask() is the key function to execute a ParallelTask.
TaskRequest	This is the request sent to the operation worker. It contains the actual request that has been replaced if there are variables defined.
SingleTask	It represents request(s) and response(s) on a single target host. For async API. there could be 1 task submission request followed by n polling requests sent out.
ResponseOnSingleTask	The final response on a single task. This class also contains the request metadata, and the each polling response. It is available in the response handler's onComplete() function
ResponseOnSingleRequest	A single response for each HTTP/SSH/TCP/Ping request.