Developing Protocol Adaptor

Nexacro basically uses HTTP to handle requests and responses. The platform does not convert data itself during the process. Depending on environments, however, you may need to encrypt data while receiving and converting certain types of data.

Protocol adapters allow you to encrypt data or change data structure with simple settings. In that way, they help you to achieve your intentions.

Creating Protocol Adaptor Module & Using It in the App

To use a protocol adapter, you need to write a module, register it in Nexacro Studio and add it as a protocol and service.

Creating Protocol Adaptor Module

1

Create a new project in the Nexacro Module Developer. Select [File > New > Project] from the menu.

2

When Project Wizard is opened, select the "Protocol Adaptor" from the Module item.

3

Enter the project ID and then click the [Next] button.

4

Enter the Object ID and then change the FinalClass item to true.

5

The project is created and the basicPtAdp.js file is displayed in the edit window.

Editing Protocol Adaptor Module

When you create a new protocol adaptor module, 4 functions are created by default.

Function

Description

initialize

The initialize function is called when the object is created.

If an external module is required, then the module is created or initialized within the initialize function.

finalize

The finalize function is called when the object is deleted.

If an external module is created or finalization is required, then the created module within the finalize function is deleted and processed so that it does not remain in the memory.

encrypt

The encrypt function is called before communication is executed. The data to be transmitted can be encrypted or converted into the desired form.

decrypt

The decrypt function is called after communication is finished. The data received in response can be decrypted or converted into the desired form.

initialize

nexacro.basicPtAdp.prototype.initialize = function()		
{	
    trace("basicPtAdp initialize");
};

In the case of the external plug-in module being used, initialize it using PluginElement as shown below.

nexacro.basicPtAdp.prototype.initialize = function()		
{	
    this._plugin = new nexacro.PluginElement();
	this._plugin.setElementClassId("Microsoft.XMLDOM");
    //this._plugin.setElementClassId("{7E9FDB80-5316-11D4-B02C-00C04F0CD404}");
    this._plugin.create();  
};

finalize

nexacro.basicPtAdp.prototype.finalize = function()		
{	
    trace("basicPtAdp finalize");
};

The external module created through the initialize function is deleted.

nexacro.basicPtAdp.prototype.finalize = function()
{
	this._plugin.destroy();            
	delete this._plugin;  
}

encrypt

The data to be transmitted is converted and processed by being put into the return string variable.

nexacro.basicPtAdp.prototype.encrypt = function(strUrl, strData)		
{	
	trace("encrypt url=" + strUrl + ";data=" + strData);
	return strData;
};

decrypt

The data received in response is converted and passed to the calling app.

nexacro.basicPtAdp.prototype.decrypt = function(strUrl, strData)		
{
	trace("decrypt url=" + strUrl + ";data=" + strData);
	return strData;
}

Deploying the Protocol Adaptor Module

1

Select the Nexacro Module Developer menu [Deploy > Module Package] and then run the Deploy Wizard.

2

Change the Type item to "protocoladaptor" in the Module Information.

3

Click the [Deploy] button to deploy the module.

Installing the Module & Registering the Protocol Service

1

Select the Nexacro Studio menu [File > Install Module] and then run the Install Module Wizard.

2

Select and install the module installation file created in the Nexacro Module Developer.

Since the registration property value among the module meta-info properties is set to the default value ("deny"), the list of modules to be installed is not displayed.

3

Select the TypeDefinition item in the Project Explorer and then select [Add > Protocol] from the context menu.

4

Set the Protocol ID and the Prefix ID in the New Protocol Wizard.

5

Click the [Next] button to check the Web Browser item and then enter the ClassName.

Calling Service through the Protocol Adaptor

When executing the transaction method, if the protocol adaptor URL format is applied to the strURL parameter as shown below, then the communication request is not directly passed to the server, but rather passes through the protocol adaptor.

this.Button00_onclick = function(obj:nexacro.Button,e:nexacro.ClickEventInfo)
{
	this.transaction("srv00", "basicPtAdp://127.0.0.1:4098/test.xml", "","dsOut=Dataset00","value=a","fnCallback");
};

this.fnCallback = function(id, code, message)
{
	trace("Error["+code+"]:"+message);
}

When you click the button, you can see that the protocol adaptor operation is processed in the following order.

  1. initialize

    There is no initialization in the example, and only the trace method is executed.

  2. encrypt

    Check that the value passed to the strArgument parameter is processed.

  3. decrypt

    Check the response data for the request.

  4. CallbackFunc

    Check that the callback function is operating after normal processing.

basicPtAdp initialize

encrypt url=basicPtAdp://127.0.0.1:8080/test.xml;data=<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="http://www.nexacroplatform.com/platform/dataset">
    <Parameters>
        <Parameter id="value">b</Parameter>
    </Parameters>
</Root>

decrypt url=basicPtAdp://127.0.0.1:8080/test.xml;data=<?xml version="1.0" encoding="utf-8"?>
<Root xmlns="http://www.nexacroplatform.com/platform/dataset" ver="5000" >
     <Parameters>
          <Parameter id="ErrorCode" type="int">0</Parameter>
          <Parameter id="ErrorMsg" type="string">SUCC</Parameter>
     </Parameters>
     <Dataset id="customers">
          <ColumnInfo>
               <Column id="id" type="STRING" size="4"/>
...

Error[0]:SAUCC

Additional Configurable Interface Functions

The protocol adaptor provides additional configurable interface functions.

Redefinable Interface Functions

The functions provided by the inherited nexacro.ProtocolAdp can be redefined. They can be added and used in the properties window.

Function

Description

getUsingProtocol

It sets the character string to be used as the protocol.

getCommunicationHeaders

It additionally sets the information in the cookie when communicating.

The getCommunicationHeaders function can be set as follows.

nexacro.basicPtAdp.prototype.getCommunicationHeaders = function (strUrl)
{
	var ret = nexacro.ProtocolAdp.prototype.getCommunicationHeaders.call(this, strUrl);
	ret.push({id:"PHPSESSID", value:"298zf09hf012fh2"});
	ret.push({id:"csrftoken", value:"u32t4o3tb3gg43"});
	return ret;
};

You can see that additional cookie information has been set when communicating.

Functions Added as Methods

Select the object in the Project Explorer and then set it by adding the method from the context menu.

Function

Description

getHTTPHeader

It sets the HTTP header value. You can specify id, value of the header value you want.

version

To use the getHTTPHeader function, you must set the version function to a value greater than "1.1".

The getHTTPHeader, version function can be set as follows.

nexacro.basicPtAdp.prototype.initialize = function()		
{	
	this._httpheaders = [];
	this._httpheaders.push({ id: "Accept", value: "application/json, text/json, */*"});
};	

nexacro.basicPtAdp.prototype.version = function ()
{
	return "1.1";
};	
	
nexacro.basicPtAdp.prototype.getHTTPHeader = function ()
{
	return this._httpheaders;
};

You can see that the header Accept information has been changed when communicating.