Calling Convention

Since version 1.0.1, XINS has the notion of calling convention.

A calling convention specified the format of the request and the format of the result. You can see it as a communication protocol.

XINS 1.1.0 includes the following calling conventions: _xins-std, _xins-old and _xins-xml.

XINS 1.2.0 includes the _xins-xslt calling convention and allows to define it's own custom calling convention.

XINS 1.3.0 includes the _xins-soap and _xins-xmlrpc calling conventions.

XINS 1.4.0 includes the automatic detection of the calling convention meaning that if no _convention parameter is sent and no custom calling convention is defined, XINS will try to detect the calling convention to call based on the format of the request.

XINS 1.5.0 includes the XINS front-end calling convention: xinsff. A front-end framework user guide is also included in the release. It is also possible since this version possible to define the supported HTTP methods for a custom calling convention. This can be useful if you want to define a REST calling convention. A new example was also added that uses a MultipartCallingConvention to receive binaries files.

XINS 2.0 includes the _xins-json and _xins-jsonrpc calling conventions. The _xins-old calling convention has been removed in this release.

XINS 2.1 includes the _xins-soap-map calling convention.

How to define the calling convention

If nothing is specified the standard calling convention (as in XINS 1.0.0) is used.

If the calling convention can be set, by adding the _convention parameter to the URL with the value of the calling convention as argument.

The default calling convention for an API can be specified in the impl.xml file by adding the calling-convention element. For example:

<impl>
  <calling-convention name="_xins-xml" />
</impl>

Standard calling convention

The standard calling convention or also named POX-RPC calling convention is the default calling convention used by xins. If no calling-convention is included in the impl.xml file and no _convention parameter is passed in the request, XINS will expect an request using this convention and return a result using this convention. The property value for the POX-RPC calling convention is _xins-std. This calling convention is also known as the standard calling convention.

This examples provided in this document are using the POX-RPC calling convention. The examples generated with the specdocs and the test forms are also using this calling convention.

A document (link) is also provided in the docs\protocol directory that contains the specifications of this calling convention.

XSLT calling convention

The property value for the XSLT calling convention is _xins-xslt. The request is similar to the standard calling convention (using URL). The result returned is the result of the processing of the XML normally returned with the standard calling convention with a specified XSLT file. This means that the result could be a HTML page or XML or plain text or binary depending on the XSLT transformation.

The location of the XSLT stylesheets is set using the runtime property templates.<api name>.xins-xslt.source. This property refers to the directory where the XSLT stylesheets can be found. The stylesheets then must have the name of the function with the .xslt extension.

You can also pass the location of the template in the request with the _template parameter. This will override the previous runtime property. The location should be relative to the path or URL specified in the runtime property templates.<api name>.xins-xslt.parameter.prefix. If this property is not set the _template parameter is not allowed.

The XSLT calling convention caches the templates for better performances. You can clear the cache by passing the _cleartemplatecache=true parameter. You can also disable the cache by setting the templates.cache runtime property to false.

SOAP calling convention

The property value for he SOAP calling convention is _xins-soap. The SOAP calling convention allows you to call the API using SOAP. SOAP is a W3C standard communication protocol for Web Services. The SOAP calling convention allows to provide to external software and companies a way to communicate using a standard protocol. The SOAP calling convention allows also to use XINS with WS-BPEL or JBI.

Example of an input request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0="urn:allinone">
  <soap:Body>
    <ns0:DataSection3Request>
      <inputText>Hello</inputText>
      <data>
        <address company="McDo" postcode="1234" />
        <address company="Drill" postcode="4567" />
      </data>
    </ns0:DataSection3Request>
  </soap:Body>
</soap:Envelope>

SOAP is often associated with a WSDL file that describes the Web Service. XINS can generate this WSDL file by executing xins wsdl-<api name>. This generated file is located in the directory build\webapps\<api>. Note that the generated WSDL file also contain the XML Schema for the standard types, the defined types, the required fields or the optional fields. By default the endpoint defined in the WSDL is the first environment defined in the environment XML file or if there is no file defined http://localhost/<api name>/?_convention=_xins-soap. You can set the endpoint by passing the command line argument -Dwsdl.enpoint or by setting the wsdl.endpoint property in build.properties file. You can then use this generated file in the Web Services client sush as C#, Visual Basic, PHP, Perl.

The SOAP calling convention and the generation of the WSDL have been developed based the WS-I Basic Profile Version 1.1 to ensure better compatibility with other frameworks.

XML calling convention

The property value for the XML calling convention is _xins-xml. In this case only HTTP POST are accepted. The returned output is the same as the standard calling convention. Example of an input request:

<request function="functionName">
  <param name="paramName">paramValue</param>
  <data>
    <product name="something1" price="12.2" />
    <product name="something2" price="23.5" />
  </data>
</request>

XML-RPC calling convention

The property value for the XML-RPC calling convention is _xins-xmlrpc. XML-RPC is a specification used to remote procedure call using XML over HTTP. XML-RPC has client frameworks in a lot of languages including AppleScript, J2ME, Ruby.

Example of an input request:

<?xml version="1.0"?>
<methodCall>
  <methodName>SimpleTypes</methodName>
  <params>
    <param><value><struct><member>
    <name>inputBoolean</name>
    <value><boolean>0</boolean></value>
    </member></struct></value></param>
  </params>
</methodCall>

For more information on XML-RPC, visit the web site at http://www.xmlrpc.com/.

JSON-RPC calling convention

The property value for the JSON-RPC calling convention is _xins-jsonrpc. JSON-RPC is a specification used to remote procedure call in different Ajax frameworks such as the DOJO toolkit. The specification of JSON-RPC are located at http://json-rpc.org/wiki/specification. Both specification version (1.0 and 1.1) are supported by the JSON-RPC calling convention.

Example of an input request for JSON-RPC 1.0:

{"method": "ResultCode", "params": ["Hallo"], "id": null}

Examples of ouput result for JSON-RPC 1.0:

{"result": {"outputTest": "Hallo"}, "error": null, "id": null}
{"result": null, "error": "AlreadySet", "id": null}

Example of an input request for JSON-RPC 1.1:

{"version": "1.1", "method": "ResultCode", "params": {"inputText": "Hallo"}}
http://www.myserver.com/path/ResultCode?inputText=Hallo

Examples of ouput result for JSON-RPC 1.1:

{"version": "1.1", "result": {"outputTest": "Hallo"}}
{"version": "1.1", "error": {"name": "AlreadySet", "code": 123, "message": "The parameter has already been given."}}

For more examples, visit the web site at http://json-rpc.org/.

The automatic detection of the matching calling convention for a request will only find request using the 1.1 specifications.

JSON calling convention

The property value for the JSON calling convention is _xins-json. This calling convention is based on the Yahoo! JSON protocol specified at http://developer.yahoo.com/common/json.html. This includes the support for the callback parameter.

Example of an input request:

http://www.myserver.com/path/ResultCode?inputText=Hallo&output=json

Examples of ouput result:

{"outputTest": "Hallo"}

Example of an input request with callback:

http://www.myserver.com/path/ResultCode?inputText=Hallo&output=json&callback=process

Examples of ouput result with callback:

process({"outputTest": "Hallo"})

This calling convention could be useful if you want to call the API from GWT (Google Web Toolkit).

SOAP-MAP calling convention

The property value for the SOAP-Map calling convention is _xins-soap-map. This calling convention accepts SOAP requests and applies the same mapping for the request or the response as what is done in the xins wsdl-to-api command.

This means that if you need to write a web service using a pre-defined WSDL, you can do it by executing xins wsdl-to-api command and pass _convention=_xins-soap-map in the URL query parameters.

The calling convention will copy the Envelop and Body XML elements as what received in the request, try to keep the same namespaces prefix and map data element attributes to sub-elements. If after the transformation not all parameters are detected and mapped correctly, you can also extend the org.xins.server.SOAPMapCallingConvention and implement you own parsing on specific parts or create your specific response.

Custom calling convention

To create your own calling convention, you need to extend the org.xins.server.CustomCallingConvention class (javadoc).

This class has two abstract methods, convertRequestImpl and convertResultImpl, that you must implement.

Note that the CustomCallingConvention extends the Manageable class, this means that you can read the bootstrap settings in the bootstrapImpl method and the runtime properties in the initImpl method.

To define the calling convention in the impl.xml, you need to add an extra argument class to the calling-convention element. For example:

<impl>
  <calling-convention name="my-convention" class="com.mycompany.myproject.MyConvention" />
</impl>

You can also define more than one calling convention, in this case one calling convention must have the attribute default="true".

Example:

<impl>
  <calling-convention name="_xins-std" default="true" />
  <calling-convention name="my-convention" class="com.mycompany.myproject.MyConvention" />
</impl>

More information on how to create your own calling convention is provided in the calling convention primer.

You can also look at the fileupload API provided in the examples that defines a CustomCallingConvention in order to upload binaries files.

Examples calling convention

Several custom calling conventions are provided in the examples. Some of them are not included in the core libraries so if you want to use them, you will need to copy the file to your project.

Here is a list of the custom calling convention used in the examples:

  • MultipartCallingConvention is defined in the fileupload API. This calling convention allows to receive files according to the HTTP file upload protocol. This calling convention requires the commons-fileupload.jar included in apis\fileupload\lib directory.

  • RESTCallingConvention is defined in the rest API. This calling convention only accepts strict REST requests.

  • The petstore example uses the FrontendCallingConvention which is a custom calling convention added to the core. More information about this calling convention can be found in the XINS Front-end Framework manual.