Java Web-Services and Overview

What is Web-service

Web-service is a piece of software which is available on internet and accessible to client using XML (Standard Inter-operable format). 

Types of Web-services

Web-services are categorized into two types based on the type of implementation. They are "BIG" web-services and "REST"ful web-services.

"BIG" Web-services

This is also called as JAX-WS (Java API for XML Web-Services). Forget about the definition, we will see the terms which denote the BIG Web-services.

• SOAP: An XML language which is used for communication between Client and Server. Abbreviated to Simple Object Access Protocol
• WSDL: The operations exposed or available on the Web-service are defined using a machine-readable language called WSDL (Web-Service Definition Language). 

Going forward, we will see more about JAX-WS and example (may be in subsequent posts).

RESTful Web-services

RESTful web-services mostly integrated with HTTP for request and response without depending on WSDL and XML messaging. RESTful (Representational State Transfer (RESTful) web service) functionality is available in JAX-RS.
As the funtionality depends on HTTP, it's stateless and more suited for ad-hoc and simple scenarios.

How it works

Think of a scenario, how we access a web-site. There is no major difference between accessing a web-site or a web-service except for few differences. First is, the response by a web-site is a human-readable where-as the response by web-service is intended for another program (mostly machine readable). Web-site content can have text, multimedia or graphical content etc, where-as the web-service returns content in XML, JSON etc formats. 

We will see contract, request and response formats/samples in JAX-WS (JAX-RS is not in the scope of the post). Just to remind

• WSDL defines set of contracts that means what are the operations are allowed on the web-service. 
• SOAP is used for carrying request and sending the response back to the client.

Sample WSDL is as below. When we look at the operation tag in bindings we will find the operations supported by the Web-service

<definitions name="MyService"
   targetNamespace="http://www.examples.com/wsdl/GetDetails.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
   <message name="GetDetailsRequest">
      <part name="firstName" type="xsd:string"/>
   </message>
 
   <message name="GetDetailsResponse">
      <part name="greeting" type="xsd:string"/>
   </message>

   <portType name="GetDetails_PortType">
      <operation name="getDetails">
         <input message="tns:GetDetailsRequest"/>
         <output message="tns:GetDetailsResponse"/>
      </operation>
   </portType>

   <binding name="GetDetails_Binding" type="tns:GetDetails_PortType">
      <soap:binding style="rpc"
         transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="getDetails">
         <soap:operation soapAction="getDetails"/>
         <input>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:myservice"
               use="encoded"/>
         </input>
  
         <output>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:myservice"
               use="encoded"/>
         </output>
      </operation>
   </binding>

   <service name="Hello_Service">
      <documentation>WSDL File for MyService</documentation>
      <port binding="tns:GetDetails_Binding" name="GetDetails_Port">
         <soap:address
            location="http://www.examples.com/GetDetails/" />
      </port>
   </service>
</definitions>

SOAP Envelope is used for request and response. It consists of

• Header (Optional): Header contains very specific information related to the application (like authentication etc).
• Body: The actual content containing the details of the Request/Response based on the context.
• Fault Block (Optional): Fault will be in response message if it contains an error. The details of the error, error number and error description will be inside the block.

Sample SOAP envelope, will be

<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:Header>
     <!-- Header Data -->
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
     <!-- Body Info -->
     <!-- Optionally fault -->
     <SOAP-ENV:Fault>
     <faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode>
     <faultstring xsi:type="xsd:string">Error Message</faultstring>
      </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the next post, we will how to create and call the web-service in Java using JAX-WS.

Happy Learning!!!!