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>

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.

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.

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.

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>

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

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.

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

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.

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.

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: