Maria Kohtla 01.03.2017 Andmevahetusplatvorm X-tee Räägin teile andmevahetusplatvormist X-tee.

Module 5 Practical part: X-road WSDL file creation for data service

Used technologies: For creation of X-road data service WSDL, server and client we use given technologies: Java (JDK 8) Apache Tomcat 8.0 Apache CXF (ver 3.2.0) Eclipse Neon (Eclipse IDE for Java EE Developers) SoapUI

Preparing Eclipse workspace There are many ways to generate Java code from WSDL file. Here we will use Apache CXF and Maven components. For that you have to install Maven to your Eclipse IDE environment with the help of the Eclipse Marketplace. Example of generating with CXF: https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/wsdl_first

Install Maven: Open Eclipse and choose from menu:  Help -> Eclipse Marketplace... Write to search: „ Maven“ Push: „Go“ Many different Maven plugins should appear in the list. Lets choose „Maven Tycho Utilities“, by pushing „Install“ button next to it. Check that all needed elements have been chosen. Choose: „Comfirm“

Choose: „I accept the terms of the license agreement“ Choose: „Finish“ Eclipse will start installing the components. After the install is completed, Eclipse will ask about the restarts, that is important for the new components to work. Let the workplace restart.

Before creating a new project, make sure that workplace has Java JDK 1 Before creating a new project, make sure that workplace has Java JDK 1.9 and Tomcat 8 set. Add them if something is missing. Open Window > Preferences > Java >Installed JREs. Make sure JDK 1.8 is set and active. If not choose Add > Directory and choose right folder from filesystem and „Finish“. Make sure new JDK is active.

Open Window > Preferences > Sever > Runntime Environments. Make sure Tomcat 8 is set. If not, choose Add > Browse and choose right folder from filesystem and „Finish“.

Creating new project Before creating WSDL file, we need to create new project: Choose from menu: File -> New ->Other -> Maven Project Choose: „Next“

Choose: „Next“ In the next window choose: „maven-archetype-webapp“ and „Next“

Fill in the mandatory fields: Group Id: project group name (ex. ee.x_road) Artifact Id: project name(ex. persons_register) Choose: „Finish“

Creating WSDL To create X-road data service WSDL we can: Take some existing WSDL file (for example person_register.wsdl file from moodle environment) and change it depending on our need. Create new WSDL file with Eclipse IDE.

To create new WSDL file in Eclipse: Next is a description of creating WSDL using Eclipse wizard. The wizard creates a minimalistic WSDL example that can be changed according to your needs. To create new WSDL file in Eclipse: Choose:  File -> New ->Other -> WSDL File Choose: Next >

Insert WSDL file name: persons_register.wsdl (the name of the example) Choose: Next >

Fill in data: Target namespace: Target namespace of your service, ex: http://persons_register.x-road.ee SOAP Binding options: choose “document literal” Choose: Finish Now the minimalistic WSDL file is created. It has one operation “NewOperation”, that meets the needs of X-roan data service.

Changing the WSDL Next we will change WSDL file to meet the needs of our service. Eclipse lets you change WSDL file in 2 ways: Change the code of the WSDL file directly, changing the code of XML in text editor with the use of XML/WSDL validation. Change WSDL in graphical editor, where WSDL/XML code is generated automatically.

Changing WSDL with graphical editor Open WSDL file, by default the graphical editor is opened. Rename the data service (WSDL operation): Choose the operation and change its name in properties window(red arrows on picture). (NB, input and output element names are changed automatically to match the operation name.

Change the structure Next lets change service input and output to match your service description. Open inline schema editor. To do that: in WSDL “Design” view click on blue arrow next to input(look at red arrow on picture)

In inline schema editor view open schema indeks-view, by clicking on icon in upper left corner(look red arrow).

Change WSDL operations input and output to match our needs. Add missing elements to service input and output. Element types can be chosen by picking “Add Complex type” in “Types” section.

To change the complex type structure, open its detailed view by clicking on the corresponding complex:

Change service input/output to mach your service specifications Change service input/output to mach your service specifications. Priorly made complex types can be used here.

Add X-road header definitions It is easier to add X-road hearer definitions in XML sours code editor. To do that we switch to source view in WSDL editor. Add X-road namespace definition xmlns:xrd=http://x-road.eu/xsd/xroad.xsd to WSDL wsdl:definitions element. Also add xsd:import element to X-road namespace for xsd import. <xsd:import namespace=http://x-road.eu/xsd/xroad.xsd schemaLocation="http://x-road.eu/xsd/xroad.xsd" />

Add WSDL message, that has X-road headers definitions. (It WSDL it is after the tag </wsdl:types>) Added 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 X-road service version number to binding/operation element: Add X-road headers to binding/operation/input ja binding/operation/output elements: <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 X-road service version number to binding/operation element: <xrd:version>v1</xrd:version> Add human-readable X-road specific descriptions with annotation/appinfo/xrd:title element: <xsd:element name="phone" type="xsd:string" maxOccurs="unbounded" minOccurs="0"> <xsd:annotation> <xsd:appinfo> <xrd:title xml:lang="et">Telefon</xrd:title> <xrd:title xml:lang="en">Phone</xrd:title> </xsd:appinfo> </xsd:annotation> </xsd:element>

Add human-readable service description in element portType/operation/documentation/xrd:title. Can be in multiple languages.   <wsdl:portType name="persons_register"> <wsdl:operation name="personList"> <wsdl:documentation> <xrd:title xml:lang="et">Isikute nimekirja küsimine nime järgi</xrd:title> <xrd:title xml:lang="et">List of persons by name</xrd:title> </wsdl:documentation>  With that, the date service WSDL is ready.

Thanks! Maria Kohtla maria.kohtla@aktors.ee X-teed tutvustavad materjalid on valminud EL struktuuritoetuse toetusskeemist “Infoühiskonna teadlikkuse tõstmine” Euroopa Regionaalarengu Fondi rahastusel.