6.1 Practical part: Creation of X-Road data service and client based on WSDL (on Java platform)

In this chapter, we create a new X-Road data service based on a previously created WSDL description of an X-Road data service and test the X-Road service with various means.

For the creation of an X-Road data service, we use the following tools: Apache CXF 3.2, Maven.

Used method: ‘Top Down’ – i.e., based on the available WSDL, we generate a Java code which can be later changed manually as necessary.

6.1.1        Creation of X-Road data service

For creating an X-Road data service, we use Eclipse’s Maven, which generates a necessary code via CXF. For this, we change the pom.xml file. Adding necessary <properties>, <dependency> and <plugin> components.

First off, add <properties> and <dependency> so that Maven would download all the necessary jar files. If necessary, all files can be downloaded manually.

<!-- properties -->











<!-- apache cxf jax-ws 3.2.0 -->


















<!-- spring framework 4.3.11 -->








After this, select Run As > Maven install on the project so that Maven would download all the necessary Jar files.

Add <plugin>, which allows for the files to be generated. For this, you have to change:

  • <sourceRoot>: catalogue where the Java files are generated. By default, it is "target/generated-sources/cxf”. Set it as, for example: “${basedir}/src/main/java“

  • <wsdl>: WSDL from which files are generated

  • <wsdlLocation>: Location where @WebService will be referring to




    <!-- plugin 4- apache cxf codegen wsdl2java goal -->






















    For generating, select on the project Run As > Maven generate-sources.

    Additional information about pom.xml: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html

    You can additionally read: http://cxf.apache.org/docs/maven-cxf-codegen-plugin-wsdl-to-java.html

<extraargs> affect how the code is generated. You can read about it: http://cxf.apache.org/docs/wsdl-to-java.html

6.1.2        Configuration of X-Road data service

For the data service to be available, you have to change src > main > webapp > WEB-INF > web.xml.

<param-value> beans file name, where you can determine the service endpoint.


<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"



http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">








<description>Apache CXF Endpoint</description>



















Set up <jaxws:endpoint> according to your data service.

  • id: the name of beans. It is not mandatory and can be skipped.

  • implementor: Java implementation of the service

  • wsdlLocation: WSDL file

  • address: service address


<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"








    <jaxws:endpoint id="personregisterSOAP"  implementor="ee.x_road.persons_register.Person_RegisterSOAPImpl"






Check the generated data service

A new data service has been generated. To make sure, check if:

    • the source code of the service has been generated into the src folder;

    • a new java package has been created, for example: ee.x_road.persons_register (the name depends on WSDL);

    • check the data service endpoint and the WSDL:

      The generated service has been activated and it responds on the address:


      (NB! here, instead of persons_register, everyone has their own Eclipse project name)


      To check the data service, enter said address into the browser, after which information will be displayed about the created data service:

  • the address of the data service endpoint

  • data service WSDL address (link to WSDL)

Check if the WSDL address of the data service will be displayed by clicking on the WSDL link, for example: http://localhost:8080/persons_register/services/person_registerSOAP?wsdl

(The exact address of the link depends on the WSDL used)

We will use this WSDL address later when setting up the service on the X-Road security server and when testing it via SoapUI.

Request response data

Generated X-Road data service guarantees constant generated data in the request response. In real life, generated data has to be removed from the code, and for obtaining data, database request has to be used.

When testing, you can use data generated in the response or change it manually.

6.1.3        Creation of X-Road Java client application

Creation of Java client application project is the same as the creation of service (see module 5). WSDL should be copied from the service into the client application because with both, the same WSDL file has to be used.


The <properties> and <dependency> in the pom.xml file are also identical to the ones added during creation of service (see “Creation of X-Road data service“ in module 6). In the <plugin> tag, <extraarg>-client</extraarg> parameter should be used instead of <extraarg>-impl</extraarg> .

Web.xml does not need to be changed, nor does beans.xml need to be created.


You need to add endpoint in the generated file of the client:

            ((javax.xml.ws.BindingProvider) port).getRequestContext().put(




Java code of the client of the data service has been generated, now check if:

  • the generated code is inside the src folder

  • the service’s exemplary call is implemented in the <PersonRegister_PersonRegister>SOAP_Client.java file’s main() method, where instead of PersonRegister, there is a name depending on the WSDL of a specific data service.

  • Initialised data objects with generated data have been created for calling the service.

Activation of service’s client program:

  • Select file *SOAP_Client.java

  • Select from the menu: Run as / Java Application

  • Check the program’s output in the console


Java client testing via X-Road security server:

  • change the service endpoint in the*SOAP_Client.java file, so that it would refer to the security server:

    // X-road : change service endpoint address to security server address


            put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://" );

  • Check if it is correct in the generated code:

    eu.x_road.xsd.identifiers.XRoadObjectType _personList_serviceObjectType =;


    eu.x_road.xsd.identifiers.XRoadObjectType _personList_clientObjectType = eu.x_road.xsd.identifiers.XRoadObjectType.SUBSYSTEM;


  • Adjust the code generated by *SOAP_Client.java by correcting the X-Road header fields that contain generated data (like during previous testing with the SoapUI program)

(If needed, you can look at an example in the sample file PersonRegister_PersonRegisterSOAP_Client.java)

Last modified: Tuesday, 4 December 2018, 1:09 PM