Chapter 4: Generating Contract–First Web Services

Contents:
• Contract–first service development
o Comparing contract–first and code–first services
o Creating portable Java artifacts
• Importing a WSDL document
o Building interoperable applications by conforming to Web Services
Interoperability (WS–I) standards
o Implementing a web service endpoint using JAX–WS

1
 Contract–First Web Services

• The contract-first approach to web services is the process of developing the web
service by first defining the service contract, typically through a WSDL (Web Services
Description Language) file.
• The contract specifies the details of the web service: what it does (operations), what
inputs it accepts (messages), what it returns (responses), and how it communicates
(protocols).
• After the contract is defined, the developer generates Java artifacts and implements the
web service based on this contract. This approach ensures that the service adheres to a
specific structure and guarantees interoperability across different platforms and
2

programming languages.
 Contract-First Service Development

• Contract-first service development starts with creating a formal description of the web
service in WSDL before writing any code.
• The service's interface and operations are pre-defined in the WSDL, which provides a
strict contract that client and server implementations must follow.
• The code is then written to conform to this contract.

3
 Comparing Contract-First and Code-First Services
Code-First Approach:
• In the code-first approach, developers first write the Java code and then generate the
WSDL automatically from it.
• Advantages:
o Quick and easy for small or internal projects.
o Less upfront work since developers don’t need to write WSDL manually.
• Disadvantages:
o Lack of control over the WSDL structure. Changes to code may unintentionally alter the
WSDL, affecting clients.
o Difficult to maintain a stable contract, especially for large systems or services consumed by
third parties.
4
 Cont’d…

• Contract-First Approach:
• In the contract-first approach, the WSDL file is created first, and then the Java code is
generated based on this contract.
• Advantages:
o Provides precise control over the service interface, ensuring stability.
o Ensures the web service contract remains stable and interoperable across platforms.
• Disadvantages:
o More upfront effort since the WSDL must be defined first.
o Requires more careful design and planning, making it more complex.
5
 Creating Portable Java Artifacts

• In the contract-first approach, once the WSDL is defined, Java artifacts (classes and
interfaces) are generated using tools like wsimport.
• These artifacts are portable, meaning they can be used across different platforms
without modification, ensuring that the service complies with the contract.
Portable Artifacts:
• Stubs: Java classes that act as proxies, allowing the client to call the service as if it
were local.
• Skeletons: Java classes that act as server-side placeholders, ready to be filled with
business logic.
6
 Cont’d…

• Example: Using the wsimport tool, you can generate the required Java classes from a
WSDL document, ensuring the service adheres to the defined contract.
• wsimport -keep -p com.example.service http://example.com/service?wsdl

• This command generates Java classes in the com.example.service package from the
WSDL file.

7
 Importing a WSDL Document

• After defining the contract in the WSDL file, the next step is to import this WSDL into
your project, where it can be used to generate the necessary Java classes and ensure the
service follows the contract.
Building Interoperable Applications by Conforming to WS-I Standards:
• WS-I (Web Services Interoperability) standards are a set of guidelines aimed at
ensuring that web services built on different platforms can interact seamlessly.
• By adhering to WS-I standards, a web service can be consumed by clients regardless of
the technology stack they use (e.g., Java, .NET, PHP).

8
 Cont’d…

• WS-I Basic Profile: This is a set of best practices that ensures web services can
communicate regardless of platform or language.
o It defines standards for:
 WSDL structure.
 XML schema definitions.
 SOAP messaging.
 Security protocols.

9
 Cont’d…

• By following WS-I standards, you can ensure that your service is truly interoperable,
meaning that clients developed in other languages can easily consume the service
without compatibility issues.
• Example: When you create a WSDL file for your service, adhering to WS-I standards
ensures that a client built in .NET or any other platform can call your service without
problems.

10
 Cont’d…

Implementing a Web Service Endpoint Using JAX-WS:

• Once the Java artifacts are generated from the WSDL, the next step is to implement the
service endpoint using JAX-WS. The endpoint is the actual class that processes client
requests and performs the business logic.
Steps:
1. Implement the generated interface from the WSDL.
2. Use the @WebService annotation to define the service class.
3. Deploy the service on a web server (e.g., Apache Tomcat).

11
 Cont’d…

• Example: Assume we have a WSDL for a temperature conversion service (Celsius to

Fahrenheit and vice versa).

Generated Interface:
@WebService
public interface TemperatureService {
double celsiusToFahrenheit(double celsius);
double fahrenheitToCelsius(double
fahrenheit);
}

12
 Cont’d…
Generated Interface:
@WebService(endpointInterface = "com.example.TemperatureService")
public class TemperatureServiceImpl implements TemperatureService {
@Override
public double celsiusToFahrenheit(double celsius) {
return (celsius * 9/5) + 32;
}
@Override
public double fahrenheitToCelsius(double fahrenheit) {
return (fahrenheit - 32) * 5/9;
}
} 13
 Cont’d…

• In previous example, the TemperatureServiceImpl class implements the generated

TemperatureService interface.
• The business logic for each operation is implemented in the respective methods.
Explanation:
• The @WebService annotation specifies that the class is a web service endpoint.
• The service implements the operations defined in the WSDL (e.g., celsiusToFahrenheit
and fahrenheitToCelsius).
• The service can then be deployed to a web server (e.g., Apache Tomcat), where it
listens for client requests.
14
 Simple example of a contract-first web service

• Here’s a simple example of a contract-first web service, which converts temperatures

between Celsius and Fahrenheit.

Step 1: Define the WSDL (Contract): The WSDL file defines the contract, specifying
the web service operations, input/output types, and the communication protocol (SOAP).

15
 Cont’d...

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

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"

targetNamespace="http://example.com/temperature"
name="TemperatureService">

…
16
 <!-- Types section defines input/output types -->
<types>
<xsd:schema
targetNamespace="http://example.com/temperature">
<xsd:element name="CelsiusToFahrenheitRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="celsius" type="xsd:double"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CelsiusToFahrenheitResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="fahrenheit" type="xsd:double"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types> 17
 <!-- PortType defines operations -->
<portType name="TemperatureServicePortType">
<operation name="CelsiusToFahrenheit">
<input message="tns:CelsiusToFahrenheitRequest"/>
<output message="tns:CelsiusToFahrenheitResponse"/>
</operation>
</portType>

<!-- Binding specifies protocol (SOAP) and action -->

<binding name="TemperatureServiceBinding"
type="tns:TemperatureServicePortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="CelsiusToFahrenheit">
<soap:operation
soapAction="http://example.com/temperature/CelsiusToFahrenheit"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
18
</operation>
 <!-- Service section provides endpoint -->
<service name="TemperatureService">
<port name="TemperatureServicePort"
binding="tns:TemperatureServiceBinding">
<soap:address
location="http://localhost:8080/temperature"/>
</port>
</service>

</definitions>

19
 Cont’d…
Step 2: Generate Java Artifacts from WSDL: You can use the wsimport tool to
generate Java classes from the WSDL file. This tool takes the WSDL as input and
generates the necessary client and server-side code.
wsimport -keep -p com.example.temperature http://localhost:8080/temperature?wsdl

This command will generate the following:

1. Service interface: com.example.temperature.TemperatureService
2. Request/response classes for the operations:
com.example.temperature.CelsiusToFahrenheitRequest and
com.example.temperature.CelsiusToFahrenheitResponse

3. A client stub to interact with the service: com.example.temperature.TemperatureServiceService

20
 Cont’d…

Step 3: Implement the Service in Java: Once the artifacts are generated, you can
implement the service logic.

Generated Interface (TemperatureService.java):

package com.example.temperature;

import javax.jws.WebService;

@WebService
public interface TemperatureService {
double celsiusToFahrenheit(double celsius);
}

21
 Cont’d…
Implementation (TemperatureServiceImpl.java):

package com.example.temperature;

import javax.jws.WebService;

@WebService(endpointInterface =
"com.example.temperature.TemperatureService")
public class TemperatureServiceImpl implements TemperatureService {

@Override
public double celsiusToFahrenheit(double celsius) {
return (celsius * 9/5) + 32;
}
}

22
 Cont’d…

Step 4: Deploy the Web Service: To make the service accessible, deploy it on a web
server like Apache Tomcat or GlassFish.
Publishing the Service Programmatically:

package com.example.temperature;

import javax.xml.ws.Endpoint;

public class TemperatureServicePublisher {

public static void main(String[] args) {
Endpoint.publish("http://localhost:8080/temperature",
new TemperatureServiceImpl());
System.out.println("Service is published and
running...");
} 23

}
 Cont’d…

Step 5: Test the Service.

• Once deployed, you can test the service by sending a request to the WSDL URL
(http://localhost:8080/temperature?wsdl) using a SOAP client, such as SoapUI, or by
writing a Java client to consume the service.

24
 Takeaways

• Contract-First Approach: The service contract (WSDL) is defined first, and the code is
generated based on this contract, ensuring that the service interface is stable and
interoperable.
• WS-I Compliance: Ensuring that your service follows WS-I standards guarantees that
it can be consumed by clients built on different platforms and technologies.
• Service Implementation: Once the WSDL is defined and Java artifacts are generated,
the developer implements the service logic in Java and deploys the service to a server,
making it available to clients.

25
THE END!!
26