JavaEE workshop #8

Viktor Martiš

(Web services, SOAP, WSDL, spring-ws)

Previous workshop

• IDEA shortcut: Ctrl + D, Ctrl + Y
• Facade pattern
• Spring MVC
• E2E testing

Contents

• IDEA shortcut: multicursor - Alt + J
• Observer pattern
• Web services
• SOAP, WSDL
• Spring-ws, soup-ui

IDEA shortcut

• IDEA shortcut:
  • select text and press Alt + J / Shift + Alt + J
  • shift + alt + left click
  • all occurrences:  Shift + Ctrl + Alt + J

Observer pattern

• the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes
• example

Web services

• Wikipedia: Method of communication between 2 electronic devices over the web.
• W3C
  • Software system designed to support interoperable, machine-to-machine interaction over a network
  • It has an interface described in a machine processable format
  • Other systems interact with the web service in a manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML serialization in conjuction with other Web-related standards

Web services

A set of standards for implementing web services:

• UDDI: Publication and discovery
• WSDL: Service description
• SOAP: Messaging
• Transport protocol: HTTP, SMTP, FTP, ...

Web service - usage scenario

Web services - roles

• Service Provider - implements the service
• Service Requestor -  utilizes an existing web service by opening a network connection and sending an request.
• Service Registry -  logically centralized directory of services. The registry provides a central place where developers can publish new services or find existing ones.

Web services links

• https://docs.oracle.com/javaee/7/tutorial/partwebsvcs.htm#BNAYK
• http://www.slideshare.net/kverbert/web-services-28668367
• http://www.slideshare.net/sagara10/web-service-introduction
• http://www.developer.com/design/article.php/3745701/Enterprise-Java-Contract-First-vs-Contract-Last-Web-Services.htm

SOAP – Simple Object Access Protocol

• v 1.1 (2000), v1.2 (2007), differences
• Lightweight messaging framework based on XML
• Supports simple messaging and RPC
• SOAP consists of
  • Envelope construct: defines the overall structure of messages
  • Encoding rules: define the serialization of application data types
  • SOAP RPC: defines representation of remote procedure calls and responses
  • Binding framework: binding to protocols such as HTTP, SMTP
  • Fault handling
• Soap supports advanced message processing:
  • forwarding intermediaries: route messages based on the semantics of message
  • active intermediaries: do additional processing before forwarding messages, may modify message
• Binary attachements - separates from the core SOAP specification

SOAP Message

• SOAP messages consist of
  • Envelope: top element of XML message (required)
  • Header: general information on message such as security (optional)
  • Body: data exchanged (required)
• Header
  • elements are application-specific
  • may be processed and changed by intermediaries or recipient
• Body
  • elements are application-specific
  • processed by recipient only
    

SOAP Message

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2001/12/soap-envelope" 
SOAP-ENV:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

   <SOAP-ENV:Header>
      ...
      ...
   </SOAP-ENV:Header>
   
   <SOAP-ENV:Body>
      ...
      ...
      <SOAP-ENV:Fault>
         ...
         ...
      </SOAP-ENV:Fault>
      ...
   </SOAP-ENV:Body>
   
</SOAP_ENV:Envelope>

SOAP message - example

<?xml version="1.0"?>

<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Body>
  <m:GetPrice xmlns:m="http://www.w3schools.com/prices">
    <m:Item>Apples</m:Item>
  </m:GetPrice>
</soap:Body>

</soap:Envelope>

SOAP message example #2

<?xml version="1.0"?>

<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Body>
  <m:GetPriceResponse xmlns:m="http://www.w3schools.com/prices">
    <m:Price>1.90</m:Price>
  </m:GetPriceResponse>
</soap:Body>

</soap:Envelope>

SOAP Processing Model

• Elements in the Header may carry SOAP-specific attributes controlling the message processing
  • attributes from namespace
    http://www.w3.org/2002/12/soap-envelope
    role, mustUnderstand, relay, encodingStyle
• "role"/"actor" attribute
  • An actor is an application that can both receive SOAP messages and forward them to the next actor. The ability to specify one or more actors as intermediate recipients makes it possible to route a message to multiple recipients and to supply header information that applies specifically to each of the recipients.
  • if processing node matches role in header it must process the header
  • special role "next": receiving node must be capable of processing header
  • special role "ultimateRceiver: receiving node must be capable of processing body
• "mustUnderstand" attribute
  • processing of header information is mandatory

SOAP Processing Model #2

• "relay" attribute
  • it indicates that the SOAP header block must not be processed by any node that is targeted by the header block, but must only be passed on to the next targeted node.
• " encodingStyle" - used to define the data types used in the document. This attribute may appear on any SOAP element, and applies to the element's contents and all child elements.
  • • "http://www.w3.org/2003/05/soap-encoding"
      • Base64
      • date
      • hexBinary …
    • "http://example.org/encoding/"
    • "http://www.w3.org/2003/05/soap-envelope/encoding/none"

SOAP - fault element

• Carries an error message
• If present, must appear as a child of <Body>
• Must only appear once
• Has the following sub-elements:
  

SOAP fault codes

SOAP - fault element example

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">
   
   <SOAP-ENV:Body>
   
      <SOAP-ENV:Fault>
         <faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode>
		 
         <faultstring xsi:type="xsd:string">
            Failed to locate method (ValidateCreditCard) in class 
            (examplesCreditCard) at /usr/local/ActivePerl-5.6/lib
            /site_perl/5.6.0/SOAP/Lite.pm line 1555.
         </faultstring>
		 
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
   
</SOAP-ENV:Envelope>

SOAP links

• http://www.tutorialspoint.com/soap/
• http://stackoverflow.com/questions/80112/whats-the-difference-between-xml-rpc-and-soap
• https://www.ibm.com/...
• https://www.w3.org/TR/SOAP-attachments

WSDL (Web Service Description Language)

• describe how to access a web service and what operations it will perform
  • abstract description of operations and their parameters (messages)
  • binding to a concrete network protocol (e.g. SOAP)
  • specification of endpoints for accessing the service
• integral part of Universal Description, Discovery, and Integration (UDDI), an XML-based worldwide business registry
• often used in combination with SOAP and XML Schema

WSDL structure

WSDL <definitions>

•  root element of all WSDL documents
•  defines the name of the web service

<definitions name="HelloService"
   targetNamespace="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/"
   xmlns:tns="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   ................................................
</definitions>

WSDL <types>

• define its inputs and outputs and how they are mapped into and out of the services
• defining the data types that are used by the web service
• WSDL is not tied exclusively to a specific typing system.
• uses the W3C XML Schema specification as its default choice to define data types.
• If the service uses only XML Schema built-in simple types, such as strings and integers, then types element is not required.
• allows the types to be defined in separate elements so that the types are reusable with multiple web services.

WSDL <types>

<types>
   <xsd:schema targetNamespace="http://example.com/stockquote.xsd"
      xmlns="http://www.w3.org/2000/10/XMLSchema">
		
      <xsd:element name="TradePriceRequest">
         <xsd:complexType>
            <xsd:all>
               <element name="tickerSymbol" type="string"/>
            </xsd:all>
         </xsd:complexType>
      </xsd:element>			
   </xsd:schema>

    <xsd:schema>
        <xsd:import namespace="http://www.example.com/calculator" 
            schemaLocation="CalculatorService_schema1.xsd" />      
    </xsd:schema>
</types>

WSDL <message>

• describes the data being exchanged between the web service providers and the consumers
• input and output
• input describes the parameters for the web service and the output describes the return data from the web service
• contains zero or more <part> parameters, one for each parameter of the web service function
• Each <part> parameter associates with a concrete type defined in the <types> container element

<message name="SayHelloRequest">
   <part name="firstName" type="xsd:string"/>
</message>

<message name="SayHelloResponse">
   <part name="greeting" type="xsd:string"/>
</message>

WSDL <portType>

• combines multiple message elements to form a complete one-way or round-trip operation
• can define multiple operations
• One way

• Request-response

<wsdl:definitions .... > 
   <wsdl:portType .... > *
      <wsdl:operation name="nmtoken">
         <wsdl:input name="nmtoken"? message="qname"/>
      </wsdl:operation>
   </wsdl:portType >
</wsdl:definitions>

<wsdl:definitions .... >
   <wsdl:portType .... > *
      <wsdl:operation name="nmtoken" parameterOrder="nmtokens">
         <wsdl:input name="nmtoken"? message="qname"/>
         <wsdl:output name="nmtoken"? message="qname"/>
         <wsdl:fault name="nmtoken" message="qname"/>*
      </wsdl:operation>
   </wsdl:portType >
</wsdl:definitions>

WSDL <portType>

• Solicit-response - service sends a message and receives a response.

• Notification

<wsdl:definitions .... >
   <wsdl:portType .... > *
      <wsdl:operation name="nmtoken" parameterOrder="nmtokens">
         <wsdl:output name="nmtoken"? message="qname"/>
         <wsdl:input name="nmtoken"? message="qname"/>
         <wsdl:fault name="nmtoken" message="qname"/>*
      </wsdl:operation>
   </wsdl:portType >
</wsdl:definitions>

<wsdl:definitions .... >
   <wsdl:portType .... > *
      <wsdl:operation name="nmtoken">
         <wsdl:output name="nmtoken"? message="qname"/>
      </wsdl:operation>
   </wsdl:portType >
</wsdl:definitions>

WDSDL  <binding>

• specific details on how a portType operation will actually be transmitted over the wire
• bindings can be made available via multiple transports including HTTP GET, HTTP POST, or SOAP
• provide concrete information on what protocol is being used to transfer portType operations
• provide information where the service is located
• multiple bindings for a single portType

<binding type="glossaryTerms" name="b1">
   <soap:binding style="document"
   transport="http://schemas.xmlsoap.org/soap/http" />
   <operation>
     <soap:operation soapAction="http://example.com/getTerm"/>
     <input><soap:body use="literal"/></input>
     <output><soap:body use="literal"/></output>
  </operation>
</binding>

WSDL <ports>

• defines an individual endpoint by specifying a single address for a binding

<service name="Hello_Service">
   <documentation>WSDL File for HelloService</documentation>
   <port binding="tns:Hello_Binding" name="Hello_Port">
      <soap:address
         location="http://www.examples.com/SayHello/">
   </port>
</service>

WSDL links

• http://www.tutorialspoint.com/wsdl/

UDDI

• Standard for describing, publishing and finding web services
• Use XML-based description files for services
• Main components
  • White pages: basic contact information about an organization
  • Yellow pages: classification of organization based on industrial categorization
  • Green pages: technical description of services offered by registered organizations
• Access to UDDI Registry
  • Standard UDDI API (accessible via SOAP)
  • Web browser
• Implementatios - jUDDI, Websphere, ...

Contract-first versus Contract-last

• Contract-first starts with designing the XML schema / WSDL and then creating the Java interface based upon the schema.
• Contract-last takes an existing Java interface and from that, creates your web service. On reflection, you’d think that this meant create a schema contract, but generally it seems to mean getting hold of some tool that will take a Java interface as an input and deliver a WSDL as an output. 
• Why contract first?

SoapUI

• API Testing Tool
• mocking web services
• video tutorial

Ares, Spring-ws, jaxb2 plugin

• SOAP
• spring-ws
• maven-jaxb2-plugin

Jaxb2 maven plugin config

<plugin>
	<groupId>org.codehaus.mojo</groupId>
	<artifactId>jaxb2-maven-plugin</artifactId>
	<version>2.3</version>
	<executions>
		<execution>
			<id>request-generate</id>
			<goals>
				<goal>xjc</goal>
			</goals>
			<configuration>
				<packageName>cz.mfcr.ares.request</packageName>
				<sources>
				  <source>${project.basedir}/src/main/resources/ares/schemas/ares/ares_request/v_1.0.1/ares_request_v_1.0.1.xsd</source>
				</sources>
			</configuration>
		</execution>
		<execution>
			<id>answer-generate</id>
			<goals>
				<goal>xjc</goal>
			</goals>
			<configuration>
				<packageName>cz.mfcr.ares.answer</packageName>
				<sources>					        
                                  <source>${project.basedir}/src/main/resources/ares/schemas/ares/ares_answer/v_1.0.1/ares_answer_v_1.0.1.xsd</source>
				</sources>
			</configuration>
		</execution>
	</executions>
</plugin>

Q&A