Practical part: Creation of WSDL file of X-Road dataservice Module 5 Practical part: Creation of WSDL file of X-Road dataservice Name Date

Tools: For creating a WSDL of the X-Road dataservice and dataservice server and the client we use the following software in the development machine: Java (JDK 7) Apache Tomcat 7.0 Apache CXF (ver 2.7.18) Eclipse Mars (Eclipse IDE for Java EE Developers) SoapUI

Creation of WSDL of X-Road dataservice For generating the Java code of X-Road dataservice based on WSDL, we use an Apache CXF component, which must be first set up in the Eclipse IDE environment, by taking the following steps: Set up Eclipse CXF Runtime: Activate Eclipse and select in the menu: Window -> Preferences -> Web Services -> CXF 2.x Preferences->Add Enter: ‘CXF Home’– Name of Apache CXF folder Select: ‘Finish’, ‘OK’

2. Create a new Eclipse project Select in the menu: File -> New ->Other -> Dynamic Web Project

Select: Next > Enter project data: Project name: <person_register> (name of your project) Dynamic web module version: select 2.5, (not default 3.0) Configuration: CFX Web Services Project v2.5 Select: ‘Finish’

Open: ‘project Properties’ -> Targeted Runtimes -> New Tomcat Installation directory: select the Tomcat 7 folder from the file system with ‘Browse’ dialogue

Creation of WSDL file For creating a WSDL of the X-Road dataservice, you can: Take some available WSDL file as basis (for this purpose, sample files of the training environment include the file person_register.wsdl) and edit it according to the needs of your service. Create a new WSDL file with Eclipse IDE tools

Creation of a new WSDL with Eclipse wizard: In order to obtain a WSDL description of X-Road dataservice, we create the frame of a new WSDL file with one minimal service by using the Eclipse wizard for creating the WSDL file. As a result we get an example of a WSDL file, which can be edited as necessary. For creating a new WSDL in the Eclipse environment, execute the following steps: Select: File -> New ->Other -> WSDL File Select: Next >

Enter data of WSDL file: File name: persons_register.wsdl (WSDL file name of database) Select: Next >

Enter the data: Target namespace: Enter namespace of your dataservice, e.g.: http://persons_register.x-road.ee SOAP Binding options: select ‘document literal’ Select: Finish Now we have generated the minimum WSDL file, including one WSDL operation ‘NewOperation’ corresponding to the X-Road dataservice.

Editing the generated WSDL Then, we will start editing the generated WSDL example to bring it into conformity with our X-Road dataservice There are two alternatives in Eclipse WSDL editor for editing WSDL: Edit the WSDL source code directly or work with XML in a text editor and use Eclipse WSDL validator during editing for validating the correctness of XML/WSDL. Edit WSDL in graphic editor, where WSDL/XML source code is generated automatically.

Adaptation of WSDL example with graphic editor Open WSDL for editing the file; graphic editor view is opened by default. Rename dataservice (or WSDL operation): Select an operation in the editor and change the name of the operation in the properties window based on the description of your dataservice (see the red highlight in the figure). !note that the names of input/output elements are also changed automatically based on the operation name

Bringing the structure of dataservice into conformity with the description of the service Now, bring the input/output of the dataservice into conformity with the description of the service. Open the inline schema computer editing programme (hereinafter the editor). Proceed as follows: on WSDL ‘Design’ view, click on the blue arrow at input (see the figure, indicated with a red arrow)

In the inline schema  editor view first open the schema index view by clicking on the relevant icon in the upper left corner ! see the figure, indicated with a red arrow

Change the operation input and output in WSDL as required (i. e Change the operation input and output in WSDL as required (i.e. according to the description of your dataservice). Add data types needed for describing the input and output of dataservice – WSDL complex types. Data types can be added in the ‘Types’ section by selecting ‘Add Complex type’.

In order to change the structure of some complex type click on the name of the relevant complex type a detailed view of the type description will open:

Add descriptions of X-Road headers In order to add X-Road header fields, it is easier to use XML source code editor, therefore we switch WSDL editor to the source code view (‘source’). Add the definition of X-Road namespace: xmlns:xrd=http://x- road.eu/xsd/xroad.xsd to the attributes of the label wsdl:definitions in WSDL.

Add a message (message) to WSDL, where X-Road header fields are defined. It’s location is in WSDL after the label </wsdl:types Add XML: <wsdl:message name="xrdheader"> <wsdl:part name="client" element="xrd:client" /> <wsdl:part name="service" element="xrd:service" /> <wsdl:part name="userId" element="xrd:userId" /> <wsdl:part name="id" element="xrd:id" /> <wsdl:part name="protocolVersion" element="xrd:protocolVersion" /> </wsdl:message>

Add descriptions of X-Road header in WSDL under elements binding/operation/input and binding/operation/output: <wsdl:input> <soap:body use="literal"/> <soap:header message="tns:xrdheader" part="client" use="literal"/> <soap:header message="tns:xrdheader" part="service" use="literal"/> <soap:header message="tns:xrdheader" part="userId" use="literal"/> <soap:header message="tns:xrdheader" part="id" use="literal"/> <soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/> </wsdl:input>   Add the version number of X-Road service in WSDL under elements binding/operation: <xrd:version>v1</xrd:version> Add a human-readable description of the dataservice to the element portType/operation/documentation/xrd:title in WSDL: <xsd:element name="phone" type="xsd:string" maxOccurs="unbounded" minOccurs="0"> <xsd:annotation> <xsd:appinfo> <xrd:title xml:lang="et">Telefon</xrd:title> </xsd:appinfo> </xsd:annotation> </xsd:element>

Add a human-readable description of the dataservice to the element portType/operation/documentation/xrd:title in WSDL <wsdl:portType name="persons_register"> <wsdl:operation name="personList"> <wsdl:documentation> <xrd:title xml:lang="et"></xrd:title> </wsdl:documentation>   Now, WSDL of X-Road dataservice is completed, all obligatory X-Road elements have been added

Thank You! First name Surname firstname.surname@amet.ee The training materials for developers of X-Road interfaces have been compiled with funding from the structural funds support scheme “Raising Public Awareness about the Information Society” of the European Regional Development Fund.