Page History
...
2a | A communications method call is made to the i2b2.CELLCODE.ajax.METHODNAME. |
2b | The generic communicator code performs a synchronous or asynchronous call to the i2b2 hive back-end and retrieves the results. |
2c | The cell communicator returns a standardized Communications Message Object containing the resultant XML as well as an optional method called parse (). |
2d | Calling the parse () method of the Communications Message Object will cause a JavaScript array called data to be added to the object which contains information extracted by the default associated parser routine. If an error is encountered data === false. |
Creating a Communicator Object
Object Instantiation and Definition of Data Namespaces
Create an instance of the generic communicator object using a call to i2b2.hive.communicatorFactory() function and save it to the ajax namespace of your cell or plug-in. You will also need to define a namespace to hold the XML message templates used to send requests to the i2b2 Hive.
...
// create the communicator Objecti2b2.ONT.ajax = i2b2.hive.communicatorFactory ("ONT"); |
Definition of XML Message
Now the individual XML message templates need to be created. These templates are simply strings saved into the msgs namespace. Best practice is to save them using a name that is the same as the i2b2 Hive RPC call.
...
Placeholder tags starting, and ending, with three curly brackets ( "{" and "
}" ) are contained throughout this message string. Between the tag's curly brackets is its non-space containing name used to identify the tag. These tags are replaced with values passed in the call parameters when the communication method is invoked.
Reserved Tag Names
There are a number of reserved tag names that are automatically defined by the i2b2 web client framework. You may (and most like will) use these tags in your message.
...
Tag Name | Example Value | Description |
{ | <proxy> | Information used by the Web Client's proxy server |
{ | HarvardDemo | Domain of current project |
{ | Demo | Code of current project |
{ | demo | User currently logged in |
{ | <password token_ms_timeout='1800000' is_token='true'> | See Documentation on Hive Project Management Cell |
{ | mQgJaD4z12dd2vLWWzY64 | Runtime generated GUID |
{ | 2010-05-19T13:24:35-04:00 | Current datetime in ISO8601 |
{ | 180 | Max query time in seconds |
Message Parser Creation
You may create a message parser to simplify your own code and to allow other developers to more easily integrate with your standardized cell communicator. When your parser is invoked its this variable references the standard Communicator Results Object ("CRO") that is returned by the communicator subsystem.
i2b2.ONT.cfg.parsers.GetSchemes = function(){ |
...
Note | ||
---|---|---|
| ||
Very specific behavior is expected from your parser function! Your parser is expected to create an array called this.model containing a list of values or JavaScript objects representing data from the XML message. If an error occurs, your parser is expected to set this.model = false. Your parser routine must always return the reference to its this variable |
Creating Communication Methods
The generic communicator object returned by calling the i2b2.hive.communicatorFactory() function consist of several private use functions and data structures. The _addFunctionCall() function is to be used by your initialization routine to create communicator methods that are to be called by non-framework code, such as the code in your cell / plug-in. To continue with this section's example and create the ONT cell's GetSchemes communication method the following code is executed:
...
Note | ||
---|---|---|
| ||
To ensure stability of your Web Client deployment, do not change the default message parser of any cell or plug-in this is not owned in-house. |
Using the Communicator
Standard Communication Method Parameters
All communication methods created using the _addFunctionCall() function of a communicator instance operate in exactly the same way and consume the same parameters. Below is a list of all parameters of a standard communications method:
Parameter | Required | Description |
originName | N | String that is used to identify and group all messages using the message sniffer subsystem. |
tagValues | N | A JavaScript object using tagname / value pairs. An example would be: |
scopedCallback | Y | A scopedCallback object or regular function used to enable asynchronous AJAX calls. |
transportOptions | Y | Transport options passed directly to Prototype's AJAX object. |
Synchronous Call Example
A code example showing how to perform a synchronous request on a standard communicator method:
// create the object containing tag/value pairs to be used by the XML msg template |
Asynchronous Call Example
Here is a code example showing how to perform an asynchronous request on a standard communicator method:
...
// create scoped-callback object (attaches execution scope to complexAsynchCallback) |
Communication Data Object ("CDO")
All standardized communication method calls, regardless of synchronous or asynchronous execution, return a standard results object known as a Communication Data Object which contains details of the messages passed back and forth between the web client and the i2b2 Hive back-end.
Attribute Name | Type | Description |
Result.error | Boolean | Information used by to Web Client's proxy server |
Result.msgRequest | String | The message that was sent to the proxy server (and thus the i2b2 Hive web service) |
Result.msgResponse | String | Code of current project |
Result.msgUrl | String | The URL used to access the i2b2 Hive web service call. |
Result.msgUrlProxy | String | The URL of the proxy that the web client sent the message to. |
Result.refXML | XMLDOM | A reference to a XMLDOM object containing the response message. |
Result.parse() | Function | A function called by a developer's code to automatically parse the XMLDOM and save the results in Result.model attribute. |
Result.model | Null or Array | This attribute is created after calling the parse() function. |
Message Parser Examples
The following code shows how to use the default parser function on a returned Communication Data Object:
...