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 in a web server. It only needs until

ParallelClient pc = new ParallelClient(); 
.setHttpHeaders(new ParallecHeader().addPair("content-type", "application/json"))
.setHttpEntityBody( "{  \"cmd\":\"  df -h; \"}")
.execute( new ParallecResponseHandler() {
    public void onCompleted(ResponseOnSingleTask res,
            Map<String, Object> responseContext) {
        System.out.println( res.toString() );  }

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
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.