JSON-RPC Protocol

JSON RPC

Refer to http://json-rpc.org/wiki/specification for details on how json-rpc calls are made and how responses/errors are returned.

In summary: A JSONRPC call is of the following structure: <source lang="javascript"> {

 "id": <number>,
 "method": <string identifying the method to call>,
 "params": [list of parameters]

} </source>

A response is of the following form: <source lang="javascript"> {

 "id" : <number>,
 "result" : <reply>,
 "error" : null or error message/object or missing if no error.

} </source>

Communicating with the WebServer

Clients can only communicate with the web server. When communicating with the ParaViewAdaptor, they still need to route the requests through the web-server. <context-root>/PWService/json is the URL for the servlet that accepts JSON requests.

Obtaining list of available RMIs

Call "system.listMethods" with no parameters to obtain a list available RMIs.

Request: <source lang="javascript"> {

 "id": <num>,
 "method" : "system.listMethods",
 "params" : []

} </source>

Response: <source lang="javascript"> {

 "id": <num>,
 "result" : ["methodname1", "methodname2", ...]

} </source>

The methods exposed are defined in: <ParaViewWebSource>/WebServer/PWService/src/java/org/paraview/ParaViewVisualizationService.java

To invoke any of the methods returned, one simply creates a JSONRPC message with the "method" string referring to the method to call, and params matching the params expected on the servlet (defined in ParaViewVisualizationService.java)

Next we will see each of these methods and how and when to use them.

Creating a new visualization session i.e. start a new ParaViewAdaptor

Visualization is done by ParaViewAdaptor which is ParaView-based application. For every visualization session, we need a new ParaViewAdaptor instance. This is referred to as a visualization session. To create a visualization session or launch an instance of ParaViewAdaptor, use the following request:

Request: <source lang="javascript"> {

 "id": <num>,
 "method": "VisualizationsManager.createVisualization",
 "params": ["session-name", "descriptive comments/text", "configuration"]

} </source>

Where the parameters are: "session-name" : is an arbitrary string used to humanly identify the session. It's merely used by the admin page when listing all sessions. "descriptive comments": arbitrary comments again used for listing on admin page. "configuration" : identifies the configuration in pw-config.properties file. Confuguration is essential to identify how to start ParaViewAdaptor as well as locations of plugin directories etc. e.g. "default"

Response: <source lang="javascript"> {

 "id": <num>,
 "result": "session-id"

} </source>

"session-id" is a unique identifier for the session. Use this for subsequent communication affecting this session.

Terminating a session

To gracefully close (or abort if close fails) a ParaViewAdaptor instance use the following request:

Request: <source lang="javascript"> {

 "id": <num>,
 "method": "VisualizationsManager.stopVisualization",
 "params": ["session-id"]

} </source>

Response: <source lang="javascript"> {

 "id": <num>,
 "result": "SUCCESS" or "ERROR <message>"

} </source>

Note that this call never returns a jsonrpc error.

Communicating with a ParaViewAdaptor instance

For all other interesting communications, one needs to talk with ParaViewAdaptor. These include requests to create visualization pipeline objects, update their parameters, get information about them etc. All these communications are made using the "invoke" request as follows:

Request: <source lang="javascript"> {

 "id": <num>,
 "method": "VisualizationsManager.invoke",
 "params":["session-id", "string message to forward to ParaViewAdaptor"]

} </source>

Response: <source lang="javascript"> {

 "id": <num>,
 "result": "string of response from ParaViewAdaptor"

} </source>

All messages sent to ParaViewAdaptor using this route themselves are JSONRPC messages (as are the responses).

The next sections explains the JSON messages that can be sent to ParaViewAdaptor. All the JSON-RPC objects created must be converted to a string and then set as the params for the invoke message e.g. <source lang="javascript"> {

 "id": <num>,
 "method" : "VisualizationsManager.invoke",
 "params" : ["session-id", "{\"id\": <num>, \"method\":\"get_module\", \"params\":[]}"]

} </source>

Communicating with ParaViewAdaptor

ParaViewAdaptor handles all JSON messages sent to it by forwarding them to the Python interpreter where they are processed. For WebServer, the ParaViewVisualizationService.java defines the exposed API similarly for ParaViewAdaptor, <ParaViewWebSource>/ParaViewAdapter/pwservice.py defines the RMI calls available.

Note that all these calls are typically routed through the WebServer in which case the requests as well as responses themselves are wrapped in another JSONRPC message as explained in the previous section.

Plugins

Getting the list of plugins available

Plugins are python scripts that are placed in a directory specified by the pw-config.properties file. To get a list of available plugins call get_plugins().

Request: <source lang="javascript"> {

 "id": <num>,
 "method": "get_plugins",
 "params": []

} </source>

Response: <source lang="javascript"> {

 "id": <num>,
 "result": ["plugin_name_1", "plugin_name_2"],
 "error" : null

} </source>

Getting list of functions available in a plugin

Once one knows the list of plugins, to know what functions are available in a particular plugin, use:

Request: <source lang="javascript"> {

 "id": <num>,
 "method": "get_plugin",
 "params": ["<plugin_name>"]

} </source>

The result is a JSON object as follows: Response: <source lang="javascript"> {

 "id": <num>,
 "result": {
           "__jsonclass__" : "Plugin",
           "__selfid__"    : "<plugin_name>",
           "__methods__"   : ["func1", "func2", func3"]
           },
 "error" : null

} </source>

Calling a function in a plugin

To call a function in a plugin, use the following form.

Request: <source lang="javascript"> {

 "id": <num1>,
 "method": "execute_command_on_plugin",
 "params": {
           "id" : <num2>,
           "method" : "<plugin-name>",
           "params" : {
                      "id": <num3>,
                      "method": "<func_name>",
                      "params": [ <params to the function> ]
                      }
           }

} </source>

Response: <source lang="javascript"> {

 "id": <num1>,
 "result": {
           "id": <num2>,
           "result": <return value from <plugin_name>.<func_name> or null>,
           "error": null
           },
 "error" : null

} </source>

Using pwsimple.py

pwservice.py defines the RMI calls available, while pwsimple.py defines all visualization specific API. pwsimple.py is a extension of ParaView's simple.py and hence has all functions defined in simple.py plus a few more. One can think of pwsimple as a special plugin available by default to all session and having a slightly different API to access it.