OpenTTCN/Knowledge base/Creating NETCONF Over SOAP XML Codec
From OpenTTCN
Home | Developer's corner | Knowledge base | Working documents | Documentation | OpenTTCN IDE | Tutorials | Training | How do I | Frequently asked questions | Technical support |
Creating NETCONF Over SOAP XML Codec
This article discusses creation of NETCONF over SOAP XML codec using XML Codec Component shipped with OpenTTCN SDK for C#. NETCONF is an XML-based IETF network management protocol used to configure network devices. NETCONF is defined in RFC 6241 and usage of NETCONF over SOAP is defined in RFC 4743.
Although this article sticks with NETCONF as an example, the same approach can be applied to test virtually any XML-based protocol using OpenTTCN and TTCN-3 - the only prerequisite being the availability of XSD schema. In this case this article can be used as a starting point for developing protocol-specific XML codec.
Tools used: Technical preview of OpenTTCN Tester 2012, more specifically version 4.2.0beta4.0, and OpenTTCN SDK for C# (shipped with OpenTTCN Tester package).
Contents |
Acquiring XML Schema
To start testing NETCONF using TTCN-3, we need to at least acquire XML Schema definition for NETCONF and SOAP protocols. Having schema we can then automatically derive TTCN-3 type definitions from XSD types defined in the schema using OpenTTCN XSD to TTCN-3 translator, what enables us writing test scripts in TTCN-3.
OpenTTCN XSD to TTCN-3 translator complies with the following ETSI standard: ETSI ES 201 873-9 V4.3.1 (2011-06) "Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; Part 9: Using XML schema with TTCN-3".
To find out more technical details about TTCN-3 code generation from an XSD source, please refer to the aforementioned ETSI standard that can be downloaded for free using the following URL: http://www.ttcn-3.org/StandardSuite.htm .
OpenTTCN XSD to TTCN-3 translator is technically a part of the importer3 command-line tool and is accessible from OpenTTCN Tester IDE as well.
Add the following XSD Schema definitions to your TTCN-3 project:
Compiling XML Schema
In this article we assume that the netconf testing session/project is used.
If you use OpenTTCN Tester IDE, XML Schema files are compiled automatically within the TTCN-3 project. To customize the encoder-produced XML namespace prefixes for defined namespace URIs, you may want to use the --define-namespace-prefix command-line option of importer3.
You can also specify this command-line option from the IDE: Project | Properties | OpenTTCN | OpenTTCN Compiler | XSD Translator Extra Arguments.
Use the 'importer3 help more' command for more details on the --define-namespace-prefix command-line option.
Example of compilation from the command-line (file compile.bat):
importer3 load -lXSD -lUsefulTypes --define-namespace-prefix xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ --define-namespace-prefix xmlns=urn:ietf:params:xml:ns:netconf:base:1.0 netconf soap-encoding.xsd soap-envelope.xsd netconf.xsd
Creating coding and decoding adapter
For general-purpose information about adapter programming using OpenTTCN SDK for C#, see Creating adapter using C#.
Adapter developed in this article is limited to fulfilling SOAP-level encoding and decoding tasks only. Real-world adapters need to handle transport-layer headers such as HTTP headers in case of SOAP over HTTP, possible encryption, authentication and transport over TCP or another bearer. These issues are discussed in greater detail in another article describing creation of adapters using Adapter Framework for C# titled Creating Adapters with Adapter Framework.
To simplify the example, we put everything into one source code file. In a real-world project it is highly recommended to refactor this functionality into several source code files.
The source code of the coding and decoding adapter is presented below.
Observe that the developed adapter is merely a wrapper around XML Codec Component that does the main job.
XML Codec Component is identified by the http://www.openttcn.com/Codecs/2011/XML URI when it is instantiated.
Testing the coding and decoding adapter
To make sure that the developed adapter performs its coding and decoding tasks correctly, we develop a small test suite showing:
- encoding of XML data specified as a TTCN-3 value into UTF-8 coded XML document;
- decoding of a UTF-8 coded XML document to a TTCN-3 value.
Hint: when using command-line compilation, use the --gen-output-dir option to see the TTCN-3 modules generated from input XSD schema files.
As an input material for the developed test suite, we use chapter 3.3 "NETCONF Capabilities Exchange" of RFC 4743 containing example of SOAP exchange between client and server.
The source code of the codec adapter test suite is presented below:
In OpenTTCN IDE you simply add the CodecTest.ttcn file to the project. If you use command line, you need to add CodecTest.ttcn to the end of the importer3 load command in compile.bat.
After you recompile the test suite, you need to launch the codec adapter binary developed earlier in Program.cs. Consult OpenTTCN manual for questions regarding adapter compilation and startup.
When the adapter is up and running, create a Run Configuration in OpenTTCN IDE and run the CodecTest test suite. From the command line you can run the test campaign as follows:
tester run -i netconf @all > campaign.log
Campaign log of an example run of the test suite is presented below:
Please observe how custom XML namespace prefixes defined for namespace URIs http://schemas.xmlsoap.org/soap/envelope/ and urn:ietf:params:xml:ns:netconf:base:1.0 using --define-namespace-prefix option affect output produced by the XML encoder.
Parameterizing XML Codec Component instance
According to OpenTTCN Codec Component guidelines, each codec component may provide extra facilities for its parameterization. A codec component instance parameter is set by calling instance SetProperty() method. You can see an example of doing so in the CD_impl class constructor developed in Program.cs.
Signature (defined in OpenTTCN.Sdk.ICodecComponent):
void SetProperty(string name, object value);
Signature (defined in OpenTTCN::SDK::CodecComponent):
virtual void setProperty(const std::string& name, void* value) = 0;
The following table enumerates properties supported by the XML Codec Component.
| Property name | Property value type (property default value) | Effect | Example |
|---|---|---|---|
|
ENABLE-XML-DECLARATION |
|
Enables or disables adding of |
cc.SetProperty("ENABLE-XML-DECLARATION", true); |
|
ENABLE-CARRIAGE-RETURN |
|
Enables or disables Windows-style (CR+LF) line endings for the XML output produced by the XML encoder. Unix-style (LF) line ending is the default. |
cc.SetProperty("ENABLE-CARRIAGE-RETURN", true); |
Source code
You can download the full source code developed in this article by following this link.
