developing web services with java ™ technology dws-4050-ee6 revision a.0

Developing WebServices with Java™Technology

DWS-4050-EE6

Revision A.0

Developing Web Services with Java™Technology

About This Course

Course Goals

On completion of this course, you should be able to:

• Understand and explain why and how web servicesframeworks can be used to deploy and consumeservices.

• Understand the trade-offs associated with the useof SOAP-based or RESTful web services.

• Understand and use the JAX-WS technology todeploy and consume web services.

DWS-4050-EE6 - Developing Web Services with Java™ TechnologyCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 Preface - v


Module 1

Introduction to WebServices

Objectives

On completion of this module, you should:

• Explore the need for web services

• Define a web service and describe the motivationbehind developing and using web services inbusiness software

• Describe the characteristics of a web service

• Describe the two major approaches to developingweb services

• Describe the advantages of developing webservices within a JavaEE container.

DWS-4050-EE6 - Developing Web Services with Java™ TechnologyCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 Introduction to Web Services 1 - 1

Exploring the Need for Web ServicesW

Web services are an emerging technology that:

• Incorporates and builds upon existing standards• Introduces a new suite of specifications and APIs for

communicating between applications across theInternet

Locate andaccess

Internet

Data orClient Application

Functionality

Standard Internetand XML-based

protocols

Copyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0

DWS-4050-EE6 - Developing Web Services with Java™ TechnologyIntroduction to Web Services 1 - 2

Developing Java™ Web Services Module 1, slide 5 of 43Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Sun Services, Revision A.2

C Sun Services

Conceptual Model

Browser

Application Web Service ApplicationServer Infrastructure Functions

SwingClient

Other ClientTypes

HeterogeneousClient Base



Developing Java™ Web Services Module 1, slide 8 of 43

Sun Services

E Exposing Application Functions as a WebService

Parts WholesalerInternet

Parts InquiryRetailer Service

OEMOrderService

InventoryDatabase

DeliveryService




Characteristics of Web Services

• Loosely coupled

• Self-describing

• Published, located, and accessed over the Internet

• Interoperable

• Language and platform neutral

• Standards based (Internet- and XML-basedprotocols)


Web Services vs Other Protocols

Traditional RPC

• Within enterprise

• Tied to programminglanguages

• Procedural

• Specific transport

• Tightly coupled

• Firewall unfriendly

• Efficient

Web Service

• Public

• Programming languageindependent

• Message driven

• Variable transports

• Loosely coupled

• Firewall friendly

• Inefficient


W Sun Services

Web Service Elements

Internettransport

protocol

XML-basedmessages

(SOAP)

(HTTP, HTTPS)

Client Service

ServiceRegistry

(ebXML, UDDI)




W Sun Services

Web Service Life CycleWeb Service Provider Web Service Registry

Create, assemble, 2 Publish Service1 and deploy

Service

Description

3 Search

6 Access

RegistryEntry

Retrieve4 serviceinformation

Descriptioninterfacelocation

service Web Service Requester

5 Create Client

Web Serviceclient

DWS-4050-EE6 - Developing Web Services with Java ™ Technology

Developing Java™ Web Services Module 1, slide 19 of 43Copyright 2010 Sun Microsystems, right 2006 Sun Microsystems, Inc. All Rights Reserved. Sun Services, Revision A.2Introduction to Web Services 1 - 8

Interacting with a Web ServiceVia Registry

Registry

Service

EntryService Provider

Searc

h

registry

Web

1Retrieve serviceinformation

URL ServiceDescription

2

Service

4 Access serviceService

Requester

Create client 3 WSClient


Interacting with a Web ServiceDirect

Service Provider

Service

WebService

Requester

Create client 2

Retrieve serviceinformation

WSClient

URL Description1

Service

3 Access service


Major Web Services ModelsThere are two models for web service architecture:

• Simple Object Access Protocol (SOAP)-based

• Representational State Transfer (REST)-based(also known as RESTful)

Common characteristics of the two models are:

• Use XML

• Rely on HTTP as a transport protocol

Key difference between the two models:

• SOAP-based web services have formal servicedefinition (using WSDL)


Sun Services

A An Interoperable Architecture

Web services are intended to operate between differentimplementation languages and platforms.

UDDI DiscoveryDiscoveryInspection

Workflow Orchestration

Service Location

Description WSDLService Description

Data TypesXML

Schema

Quality of Service Security Transactions

Message Extensibility

SOAP Messaging SemanticsWire

Data Encoding Rules Network Transport

XML HTTP

Developing Java™ Web ServicesDWS-4050-EE6 - Developing Web Services with Java™ Technology

Module 1, slide 39 of 43CopyrigCopyright2010 Sun Microsystems,Inc.AllRightsReserved.RevisionA.0, Inc. All Rights Reserved. Sun Services, Revision A.2 Introduction to Web Services 1 - 12

Development Approaches

Java Java Java

WSDL WSDL WSDLXML XML XMLHTTP HTTP HTTP

Code First Contract 1st Meet in theMiddle


Code First Approach• Annotate your code.

• Deploy it in a container that supports JAX-WS,JAX-RS.

• The JAX-WS runtime will:> Generate WSDL

> Translate SOAP request to a Java technology-basedmethod invocation> Translate method return into a SOAP response

• The JAX-RS runtime will:

> Translate HTTP request to a Java technology-basemethod invocation> Translate method return into HTTP response


Contract First Approach

• "Compile" the WSDL for the service that you wouldlike to deploy.

> wsimport reads the WSDL and generates and interfacefor each portType .

• Create a class that implements each interface. Thebusiness logic of these classes implements yourWeb services.

• Deploy these Service Endpoint Implementationclasses to a JAX-WS container.


Web Service Endpoints

Although almost any Java component could act as aweb service, there are three primary models for aservice endpoint as represented by a Javacomponent:

• Astand-aloneJavaapplicationcanlistenforSOAPmessages and respond appropriately.

• The servlet service endpoint model - the mostcommon endpoint type.

• The Enterprise JavaBeans™(EJB™) serviceendpoint model.


A Simplest Web Servicecom.example.jaxws.server.AirportManager

1@WebService

2public class AirportManager {

3public long

4addAirport(String code, String name) {

5return dao.add(null, code, name).getId();

6}

7private AirportDAO dao = new AirportDAO();

8}


Simple POJO WS Client

1

2

3

4

5

6

7

8

9

10

11

12

public class SimpleClient {public static void main(String[] args) {

AirportManagerService service =new

AirportManagerService();AirportManager port =service.getAirportManagerPort

();java.lang.String code = "LGA";java.lang.String name = "New York LaGuardia";

long result = port.addAirport(code, name);System.out.println("Result = "+result);

}}


JavaEE Web Service SupportAs of version 1.4, the Java Platform, EnterpriseEdition (JavaEE) platform adds native support forweb services:

• Both servlet and EJB containers can host webservice components and service endpoints.

• All three Java 2 Platform, Enterprise Edition(J2EE™) containers offer client-sideimplementations of the web service APIs.

• JMS defines a standard for asynchronousmessaging, which could play a role in SOAPinteractions.


JavaEE 6 Specification

Applet Container

HTTPApplet SSL

Java SE HTTP

SSL

Application ClientContainer

ApplicationClient

SAAJ

Java SE

Copyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 DWS-4050-EE6 - Developing Web Services with Java™ Technology

Web Container EJB Container

JSP Servlet EJB

SAAJ SAAJ

Java SE Java SE

Database

New in Java EE 6

Introduction to Web Services 1 - 20

Session Beans as Service Endpoints

Web service endpoints implemented in sessionbeans benefit from the EJB component model’ssupport for enterprise features:

• Declarative, even implicit, transaction control

> transparent injection of JPA EntityManager andpersistence context

• Declarative Security Authentication andAuthorization

• Scalability through pooling

• Availability through clustering



Module 2

Using JAX-WS

ObjectivesOn completion of this module, you should:

• Understand how to create web services usingJAX-WS:

> Bottom-up, starting from Java classes> Top-down, starting from WSDL descriptions

• Understand how to deploy web services providersusing JavaSE.

• Understand how to create and deploy simple webservices clients using JavaSE.

DWS-4050-EE6 - Developing Web Services with Java™ TechnologyCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 Using JAX-WS 2 - 1

Overview of JAX-WS

Java API for XML Web Services (JAX-WS):

• Is a technology for building web services andclients that communicate using XML

• Supports message-oriented and RPC-orientedweb services

> even RESTful web services, with a bit of work...

• Relies heavily on the use of annotations

• Supports WS-I Basic Profile 1.1

• Hides the complexity of SOAP interaction from thedeveloper


JAX-WS Development Approaches

• Generate web service artifacts using theinformation contained in a WSDL file

• Create service endpoint interface (SEI) or valueclasses as Java source files, and then use them asinputs to generate the associated WSDL descriptorand other portable artifacts

In either case, JAX-WS generates the majority of theinfrastructure code required by the service.


J Sun Services

JAX-WS - Artifacts

WSDLDescriptor

JavaInterfaces

JAX-WSAnnotated

Service EndpointImplementationClasses

Code Generator JAXB beans

WSDLDescriptor

DWS-4050-EE6 - Developing Web Services with Java ™ TechnologyCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0Using JAX-WS 2 - 4

Creating Web Services Using Java™ Technology Module 8, slide 7 of 46Copyright 2008 Sun Microsystems, Inc. All Rights Reserved. Sun Learning Services, Revision A.2

Advanced Features of JAX-WS

• Provides a flexible plug-in framework for messageprocessing modules called handlers

• Provides JAX-WS SOAP binding and JAX-WSXML/HTTP binding

• Provides Dispatch API for those web service clientapplications which work at the XML message level

• Provides support for asynchronous interactions

• Provides support for stateful interactions


Creating a Web Service Using JAX-WSBottom-Up Approach

Starting from a Java class:

• For creating a web service that exposes thefunctionality of an existing application or creatingfrom scratch.

• When you start with a suite of applicationcomponents, generate the necessary web servicedescriptive and infrastructure files based on thefunctionality provided by the existing components.


A Simple Service: AirportManagercom.example.standalone.AirportManager


2public long



5}


7}


A Simplest Web Servicecom.example.jaxws.server.AirportManager

1@WebService


3public long



6}


8}


JAX-WS RequirementsRequirements on the Java Class

• Must be annotated with javax.ws.WebService• Must not be declared final

• Must not be abstract• Must have a default public constructor

• Must not have a finalize method


JAX-WS RequirementsRequirements on Web Service Methods

• Must be publicBy default, every public method in the class will bepart of the web service.

• must not be static or final• must have JAXB-compatible parameters and returntypes

> Parameters and return types must not implement thejava.rmi.Remote interface.


Generating Portable ArtifactsWSDL Description and Supporting Files

• JAX-WS might need additional artifacts to supportthe web service provider:

> JAXB classes, to represent SOAP messages> AWSDLfile,forclientstoaccessthewebservice

• These can be generated using apt or wsgenapt [-d outputDir] sourceFile ...wsgen [-d outputDir] classFile ...

> JAX-WS can deliver WSDL descriptions dynamically:

http://host:port/path/to/service?WSDL


Generated WSDLDefault WSDL Description

1

2

3

4

5

6

7

8

9

10

11

12

<message name="addAirport"><part name="parameters"

element="tns:addAirport"/></message><message name="addAirportResponse">

<part name="parameters" element="tns:addAirportResponse"/></message> <portType name="AirportManager">

<operation name="addAirport"><input message="tns:addAirport"/>

<output message="tns:addAirportResponse"/></operation>

</portType>


Generated XML SchemaDefault XML Schema

1

2

3

4

5

6

7

8

9

10

11

12

13

14

<xs:element name="addAirport" type="tns:addAirport"/><xs:element name="addAirportResponse"

type="tns:addAirportResponse"/><xs:complexType name="addAirport">

<xs:sequence><xs:element name="arg0" type="xs:string" minOccurs="0"/>

<xs:element name="arg1" type="xs:string" minOccurs="0"/></xs:sequence>

</xs:complexType><xs:complexType name="addAirportResponse">

<xs:sequence><xs:element name="return"

type="xs:long"/></xs:sequence></xs:complexType>


Sample SOAP Request

1

2

3

4

5

6

7

8

9

10

<S:Envelope xmlns:ser="http://server.jaxws.example.com/"xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Header/><S:Body>

<ser:addAirport><arg0>JFK</arg0>

<arg1>New York Kennedy Airport</arg1></ser:addAirport></S:Body>

</S:Envelope>


Sample SOAP Response

1<S:Envelope

2xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

3<S:Body>

4<ns2:addAirportResponse

5xmlns:ns2="http://server.jaxws.example.com/">

6<return>1</return>

7</ns2:addAirportResponse>

8</S:Body>

9</S:Envelope>


Raw SOAP/HTTP Request1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

POST http://localhost:8080/airportManager HTTP/1.1Accept-Encoding: gzip,deflate

Content-Type: text/xml;charset=UTF-8SOAPAction: ""

Content-Length: 346


<S:Header/><S:Body>



</S:Envelope>


Raw SOAP/HTTP Response

1

2

3

4

5

6

7

8

9

10

11

12

13

HTTP/1.1 200 OKTransfer-encoding: chunked

Content-type: text/xml; charset=utf-8

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body>

<ns2:addAirportResponsexmlns:ns2="http://

server.jaxws.example.com/"><return>1</return></

ns2:addAirportResponse></S:Body></S:Envelope>


Custom WSDL Description

1

2

3

4

5

6

7

8

9

10

11

@WebService(portName="AirportMgr",serviceName="Managers")

public class NamedAirportManager {@WebMethod (operationName="add")

public longaddAirport(@WebParam(name="code") String code,

@WebParam (name="name") String name) {return dao.add(null, code,

name).getId();}private AirportDAO dao = new

AirportDAO();}


Generated WSDLCustomized WSDL Description ...

1

2

3

4

5

6

7

8

9

10

11

12

13

<portType name="NamedAirportManager"><operation name ="add">

<input message="tns:add"/><output

message="tns:addResponse"/></operation></portType>

<service name="Managers">

<port name="AirportMgr" binding="tns:AirportMgrBinding"><soap:address

location="http://localhost:8080/namedManager"/></port> </service>

... and the Custom XML Schema

1

2

3

4

5

6

7

8

9

10

11

12

13

<xs:element name="add" type="tns:add"/><xs:element name="addResponse" type="tns:addResponse"/><xs:complexType name="add">

<xs:sequence><xs:element name="code" type="xs:string" minOccurs="0"/>

<xs:element name ="name" type="xs:string" minOccurs="0"/></xs:sequence>

</xs:complexType><xs:complexType name="addResponse">




Custom WSDL DescriptionOverloaded Methods

Web services require unique names for each method:

1

2

3

4

5

6

7

8

9

10

@WebServicepublic class BetterAirportManager {

@WebMethod ( operationName ="removeById")public void removeAirport(long id) {}

@WebMethod(operationName="removeByCode")public void removeAirport(String code) {}

// ...}


Generated WSDL"Overloaded" Operations

1

2

3

4

5

6

7

8

9

10

11

<portType name="BetterAirportManager"><operation name="removeById">

<input message="tns:removeById"/><output

message="tns:removeByIdResponse"/></operation><operation name="removeByCode">

<input message="tns:removeByCode"/><output

message="tns:removeByCodeResponse"/></operation> </portType>

Custom WSDL DescriptionDefault XML Namespace

• default XML namespace is computed:

package com.example.security.server;

produces

1<definitions

2targetNamespace=

3"http://server.security.example.com/"

4... />


Custom WSDL DescriptionCustom XML Namespace

• Set targetNamespace attribute to @WebService

1@WebService(

2targetNamespace="urn://com.example.managerNS")

3public class NamespacedAirportManager {

produces

1<definitions

2targetNamespace="urn://com.example.managerNS/"

3... />


Creating a Web Service Using JAX-WSTop-Down Approach

Use the WSDL-to-Java development approach whenyou create a web service that is not based on existingapplication components:

• Create or obtain a service description file thatspecifies the characteristics of the service

• Generate a service endpoint interface

• Implement the required web service applicationcomponents


Structure of a WSDL file

<definitions>: Root WSDL Element

<types>: What data types will be transmitted?

<message>: What exact information is expected?

<portType>: What operations (functions) will be supported?

<binding>: How will the messages be transmitted on the wire?What SOAP-specific details are there?

<service>: Define the collection of ports that make up the service and whereis the service located?


Definition of a Service Using WSDLservicehas a

collectionof ports

service

name

each porthas a

portType

portType

name

port

0..*

portTypehas a

collectionof ops

operation

0..*

port

name

operation

nameparameterorder

binds portto portType

withprotocoldetails

binding

name

operationmessagehas has

partmessage

input part0..1 message

output part name0..1 name 0..* element

fault type

0..*

DWS-4050-EE6 - Developing Web Services with Java™ Technology

UML Map of XML Elements and AttributesCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 Using JAX-WS 2 - 29

Creating WSDLWSDL Description (1 of 2)

1

2

3

4

5

6

7

8

9

10

11

12

13

14

<?xml version="1.0" encoding="UTF-8"?><definitions name="PassengerManagerPort.wsdl"xmlns="http://schemas.xmlsoap.org/wsdl/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"xmlns:tns="urn://Traveller/"

targetNamespace="urn://Traveller/"><types> <xsd:schema>

<xsd:import namespace="urn://Traveller/"schemaLocation="PassengerManagerSchema.xsd"/>

</xsd:schema></types>


Creating WSDLWSDL Description (2 of 2)

15

16

17

18

19

20

21

22

23

24

25

26

27

<message name="addPassengerRequest"><part name="params"

element="tns:addPassenger"/></message><message name="addPassengerResp">

<part name="params" element="tns:addPassengerResponse"/></message><portType name="PassengerManager">

<operation name="addPassenger"><input name="in1" message="tns:addPassengerRequest"/>

<output name="out1" message="tns:addPassengerResp"/></operation>

</portType></definitions>


Creating WSDLWSDL Schema

1

2

3

4

5

6

7

8

9

10

11

12

13

<xsd:schema id="PassengerManagerSchema.xsd"xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:tns="urn://Traveller/"elementFormDefault="qualified"

targetNamespace="urn://Traveller/"><xsd:element name="addPassenger">

<xsd:complexType><xsd:sequence>

<xsd:element name="firstName" type="xsd:string"/><xsd:element name="lastName" type="xsd:string"/>

</xsd:sequence></

xsd:complexType></xsd:element>


Creating WSDLWSDL Bindings

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

<binding name="binding" type="tns:PassengerManager"><soap:binding style="document"

transport="http://schemas.xmlsoap.org/soap/http"/><operation name="addPassenger"><soap:operation/>

<input><soap:body use="literal"/></input><output><soap:body use="literal"/></output>

</operation></binding>

<service name="PassengerManagerService"><port name="PassengerManager" binding="tns:binding">

<soap:addresslocation="http://localhost:8080/

passengerManager"/></port> </service>


Generating Implementation ArtifactsThe wsimport tool is a command-line tool to import aWSDL and to generate a SEI interface.

• The generated interface can be either:> Implemented on the server to build a web service, or> Used on the client to invoke the web service

• Some of the important command-line switchesinclude:

> -d - location of generated class files> -s - location of generated source files

wsimport http://host:port/path?wsdlwsimport PassengerManagerService.wsdl


Generated Java SEI

1

2

3

4

5

6

7

8

9

10

11

12

13

package com.example.generated;@WebService(name = "PassengerManager",

targetNamespace = "urn://Traveller/")public interface PassengerManager {@WebMethod

public long addPassenger(@WebParam(name = "firstName",

targetNamespace = "urn://Traveller/")String firstName,@WebParam(name = "lastName",

targetNamespace = "urn://Traveller/")String lastName);

}


Service Implementation Class

1

2

3

4

5

6

7

8

9

10

11

12

13

@WebService(endpointInterface=

"com.example.generated.PassengerManager")public class PassengerManagerimplements com.example.generated.PassengerManager {

public longaddPassenger(String firstName, String lastName) {

Passenger newPassenger =new Passenger(firstName, lastName, null,

null);return dao.add(null, newPassenger ).getId();}

private PassengerDAO dao = new PassengerDAO();}


Customizing Generated Code

• Just as in the Java-to-WSDL scenario, one cancustomize:

> the package name where generated classes will be placed> the name for the type generated for a WS port> the name for the method generated for a WS operation

• developer can introduce overloading in the generated code

• There are two ways to specify this customizationdetail:

> embedded declarations within the WSDL file> separate customization XML file


Embedded CustomizationCustom Package Name

1

2

3

4

5

6

7

8

9

10

11

12

13

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

<jaxws:bindingsxmlns:jaxws="http://java.sun.com/xml/ns/jaxws"><jaxws:package name="com.example.custom"/>

</jaxws:bindings><service name="CustomPassengerManagerService">

<port name="CustomPassengerManager"binding="tns:CustomPassengerManagerBinding

"><soap:addresslocation="http://localhost:8080/

customManager"/></port> </service>


Embedded CustomizationCustom Class Name

1

2

3

4

5

6

7

8

9

10

11

<definitions name="CustomPassengerManagerPort.wsdl"xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"

xmlns="http://schemas.xmlsoap.org/wsdl/"><portType name="CustomPassengerManager">< jaxws:bindings >

<jaxws:class name="CustomManager"/></jaxws:bindings></portType></definitions>

Embedded CustomizationCustom Method Name

1

2

3

4

5

6

7

8

9

10

11

12

13

<definitions name="CustomPassengerManagerPort.wsdl"xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"

xmlns="http://schemas.xmlsoap.org/wsdl/"><portType name="CustomPassengerManager"><operation name="addPassenger">

<jaxws:bindings><jaxws:method name="add"/></jaxws:bindings>

</operation></

portType></definitions>

Generated CodeFrom Customized WSDL

1

2

3

4

5

6

7

8

9

10

11

12

13

package com.example.custom;@WebService(name = "CustomPassengerManager",

targetNamespace = "urn://Traveller")public interface CustomManager {

@WebMethod(operationName = "addPassenger")public long add(

@WebParam(name = "firstName",targetNamespace = "urn://Traveller")

String firstName,@WebParam(name = "lastName",

targetNamespace = "urn://Traveller")String lastName);

}


Schema Validation

• JAX-WS won’t validate web service calls againstXML schema constraints unless requested:

1

2

3

4

5

6

7

8

9

10

11

12

@SchemaValidation@WebService(endpointInterface=

"com.example.generated.PassengerManager")public class PassengerManagerimplements com.example.generated.PassengerManager {

public longaddPassenger(String firstName, String lastName) {

Passenger newPassenger =new Passenger(firstName, lastName, null,

null);return dao.add(null, newPassenger ).getId();}


Comparing Development Approaches

• Each of the development approaches has benefitsand costs, and is best suited to specific scenarios.

• You should decide on a specific developmentapproach based on the needs of the developmenteffort.


Strong Typing for Web ServicesA benefit of the top-down approach

Fully worked WSDL can specify data and messagetypes to fine granularity, using the full power of XMLschema and allowing clients as well as servers tovalidate message content locally as follows:

• When you generate Java from WSDL, you canmap strong XML types to Java and validate thosetypes using generated code.

• When you generate WSDL from Java, thegenerated types are weaker.


Benefits of a Bottom-Up ApproachWhen you provide a web service interface to an

existing enterprise application, you should work fromJava code:

• You can use the quickest development path.

• It is a natural approach, especially when businesslogic has already been implemented.

• You can map existing domain models directly toWSDL with little effort.

• You can re-use a service facade as a mediator tothe domain logic for other types of applications andclients.


Benefits of a Top-Down ApproachWorking from WSDL provides the followingadvantages:

• WSDL is better suited when the service developeris not also the author of the service.

• The strong typing is shared using the WSDL fileitself.

• Interoperability is easier to achieve.

• Serializable types are expressed first in the XMLschema and then mapped to one or more programlanguages and object models.

• Client-side validation is easier to implement.DWS-4050-EE6 - Developing Web Services with Java™ Technology

Copyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 Using JAX-WS 2 - 46

Deploying POJO WS Providers

There are two ways to deploy a POJO Web ServiceProvider:

• Use the Endpoint machinery in JAX-WS onJavaSE

• Rely on a web container that includes support forJAX-WS


A Simplest Web Service (Recap)com.example.jaxws.server.AirportManager

1@WebService


3public long



6}


8}


Simple Standalone Server

1

2

3

4

5

6

7

8

9

10

11

12

public class AirportManager {// ...

static public void main(String[] args) {String url ="http://localhost:8080/

airportManager";if (args.length > 0)url = args[1];

AirportManager manager = new AirportManager();Endpoint endpoint =

Endpoint.publish(url, manager);} }


Finer Control over Standalone Server

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

public class FancyServer {public static

void main( String[] args ) throws Exception {HttpServer server =

HttpServer.create(new InetSocketAddress(8080),10);Executor executor = Executors.newFixedThreadPool(10);server.setExecutor(executor);

HttpContext context =server.createContext("/fancyServer");

AirportManager manager = new AirportManager();Endpoint endpoint = Endpoint.create(manager);endpoint.publish(context);

server.start();} }


Viewing SOAP Messages

Sometimes, it helps to dump all SOAP messagesexchanged by the server to standard out:

• JAX-WS includes a generic framework that can beused for this: JAX-WS Handlers.

• The system propertycom.sun.xml.ws.transport.http.HttpAdapter.dumpwhen set to true will prompt JAX-WS to do so.


Testing a Web Service

• In Glassfish,http://hostname/webService?Tester

generates a web page that can be used to test theweb service specified by the URI.

> This only works for operations whose arguments aresimple types.

• the SoapUI plugin for NetBeans/Eclipse willgenerate test suites for all operations in a webservice

• acustomwebservicesclient


Developing Web Service Clients

wsimport tool

Generates WSDLService Contract

@WebServiceDynamic Proxy

You developClient

which calls proxy


DWS-4050-EE6 - Developing Web Services with Java™ TechnologyUsing JAX-WS 2 - 53

Simple POJO WS Client

1

2

3

4

5

6

7

8

9

10

11

12

public class SimpleClient {public static void main(String[] args) {

AirportManagerService service =new

AirportManagerService();AirportManager port =service.getAirportManagerPort

();java.lang.String code = "LGA";java.lang.String name = "New York LaGuardia";

long result = port.addAirport(code, name);System.out.println("Result = "+result);

}}



Module 3

SOAP and WSDL

Objectives

On completion of this module, you should be able to:

• Understand the basic structure of a SOAPmessage, and how it is encapsulated by transports

• Understand how WSDL defines a web service,including its message representation and transportmechanism

• Understand the different styles of SOAP messagesthat a web service can use, and their trade-offs

• Customize a web service to control the style ofSOAP message that that web service will use

DWS-4050-EE6 - Developing Web Services with Java™ TechnologyCopyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 SOAP and WSDL 3 - 1

Why Use SOAP?

The web services specification sets out to define aninteroperable, platform-independent means forcomponent interaction. Among their requirements:

• decouple message representation from transportmechanisms

• support extensible frameworks


A Simple Web Service Interaction

CLIENT INVOKE ACTIVITY


Extensible Web Service Interactions

SOAP/ SOAP/Initial HTTP

IntermediaryHTTP Intermediary send accross network

Sender (adds securitytoken) (adds encryption)

SOAP/receive accross network Intermediary

HTTPIntermediary Ultimate

(decrypts (validates security Receivermessage) token)


Extensible Message RepresentationSimple Object Access Protocol

Communication ProtocolEnvelope (HTTP, SMTP. . .)

SOAP1.1 + AttachmentsMIME Envelope

SOAP Part

SOAP-ENV: Envelope

SOAP-ENV: Header

SOAP-ENV: Body

Attachment Part

SOAP Attachment(XML or non-XML)


Sample SOAP Request

1

2

3

4

5

6

7

8

9

10


<S:Header/><S:Body>



</S:Envelope>


Sample SOAP Response

1<S:Envelope

2xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

3<S:Body>

4<ns2:addAirportResponse

5xmlns:ns2="http://server.jaxws.example.com/">

6<return>1</return>

7</ns2:addAirportResponse>

8</S:Body>

9</S:Envelope>


SOAP over HTTPHTTP Message

Content-Type: multipart/related;

HTTP Headers

MIME Package

SOAP

Content-Type:text/xml

GIF Attachment

Content-Type:image/gif

boundary="MIME_Boundary";type=text/xml;

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body><getName>

<name>SomeCompany</name>

<photo href="cid:[email protected]"/></getName>

</SOAP-ENV:Body></SOAP-ENV:Envelope>

R0lGODlhHAJSAaIAAKOgpc/N0E9PTyAgIHJDknp5e0oNc////yH5BAAAAAAALAAAAAAcAlIBAAP /aLrc/jDKSau9OOvNu/9gKI5kaZ5oqq5s675wLM90bRtHru987//AoHBILBqPyKRyyWw6n9CoEq tWq8/BnbL


Raw SOAP/HTTP Request1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

POST http://localhost:8080/airportManager HTTP/1.1Accept-Encoding: gzip,deflate

Content-Type: text/xml;charset=UTF-8SOAPAction: ""

Content-Length: 346


<S:Header/><S:Body>



</S:Envelope>


Raw SOAP/HTTP Response

1

2

3

4

5

6

7

8

9

10

11

12

13

HTTP/1.1 200 OKTransfer-encoding: chunked

Content-type: text/xml; charset=utf-8

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body>

<ns2:addAirportResponsexmlns:ns2="http://

server.jaxws.example.com/"><return>1</return></

ns2:addAirportResponse></S:Body></S:Envelope>


Structure of a WSDL file

<definitions>: Root WSDL Element

<types>: What data types will be transmitted?

<message>: What exact information is expected?

<portType>: What operations (functions) will be supported?

<binding>: How will the messages be transmitted on the wire?What SOAP-specific details are there?

<service>: Define the collection of ports that make up the service and whereis the service located?


Defining a Web Service in WSDLser

vice

name

portT

ype

name

+part

0..*

+operation

0..*

p

ort

name

bin

ding

name

+input

operation 0..1 message

name +output nameparameterOrder 0..1

+fault

0..*

+port

0..*

part

name

elementtype


WSDL Interaction ScenariosOne-way Request/Response

Client Service Client Service

Solicit/Response Notification

Client Service Client Service


Logical vs ImplementationDescriptions

• <portType>, <operation> and <message>represent the logical description of a web service:what the service can do.

• WSDL files also provide some implementationguidance:

> XML schemas define the representation of the dataembedded in messages> WSDL bindings provide additional guidance:

• Style of WSDL to use


WSDL Bindingsbinding

type=”MyInterface”

soap:binding <...>

operationname=”Method1”

input

soap:body <...>

output

soap:body <...>

portTypename=”MyInterface”

operationname=”Method1”

inputmessage=”MyParams”

outputmessage=”Results”


Describing SOAP Messages

1

2

3

4

5

6

7

8

9

10

11

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ser="http://server.jaxws.example.com/">

<S:Header/><S:Body>

<ser:addAirport>< code >JFK</ code >

<name>New York John F. Kennedy Airport</name></ser:addAirport> </S:Body>

</S:Envelope>

• How many ways to construct this request?

• How many ways to describe a given structure?


Variations of WSDLDesigners have to make two choices, when writingWSDL descriptions for web services:

• What "style" of WSDL definition to use

> RPC-style> Document-style

• What data representation to use

> literal> SOAP/RPC encoded (discouraged)


RPC Style

• Every input message results in a SOAP body witha single element that represents the function to becalled, and which contains its parts

• Messages can have multiple parts:

> Every part of an input message is a parameter to thefunction call

> every part of an output message is a return value from thefunction call

• Every part is described by a builtin XML schematype, or by a complex type defined by the WSDLfile


RPC Style<portType>

1

2

3

4

5

6

7

8

9

10

11

<portType name="RPCLiteralAirportManager"><operation name="addAirport"

parameterOrder="code name"><input message="tns:addAirport"/><output

message="tns:addAirportResponse"/></operation><operation name="findNeighbors">

<input message="tns:findNeighbors"/><output

message="tns:findNeighborsResponse"/></operation></portType>

rpcLiteralManager.wsdl


RPC Style<message>

1<message name="addAirport">

2<part name="code" type="xsd:string"/>

3<part name="name" type="xsd:string"/>

4</message>

5<message name="addAirportResponse">

6<part name="return" type="xsd:long"/>

7</message>



RPC Style<binding>

1

2

3

4

5

6

7

8

9

10

<binding name="AirportMgrBinding"type="tns:RPCLiteralAirportManager">

<soap:binding style="rpc"transport="http://schemas.xmlsoap.org/soap/

http"/><operation name="addAirport"><soap:operation soapAction=""></soap:operation><input>

<soap:body use="literal"namespace="http://

server.jaxws.example.com/"/></input>



RPC StyleSample Message

1

2

3

4

5

6

7

8

9

10

11

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ser="http://server.jaxws.example.com/">

<S:Header/><S:Body>

<ser:addAirport><code>JFK</code>

<name>New York John F. Kennedy Airport</name></ser:addAirport></S:Body>

</S:Envelope>


RPC Style<message>

1<message name="findNeighbors">

2<part name="code" type="xsd:string"/>

3</message>

4<message name="findNeighborsResponse">

5<part xmlns:ns1="http://jaxb.dev.java.net/array"

6name="return" type="ns1:stringArray"/>

7</message>



RPC Style<schema>

1<xs:complexType name="stringArray" final="#all">

2<xs:sequence>

3<xs:element name="item"

4minOccurs="0" maxOccurs="unbounded"

5nillable="true" type="xs:string" />

6</xs:sequence>

7</xs:complexType>

rpcLiteralManager.xsd


RPC StyleSample Response

1

2

3

4

5

6

7

8

9

10

11

12

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/

envelope/"><S:Body> <ns2:findNeighborsResponse

xmlns:ns2="http://server.jaxws.example.com/"><return><item>JFK</item>

<item>SFO</item></return>

</ns2:findNeighborsResponse></S:Body></S:Envelope>


RPC/literal StyleJava-to-WSDL Specification

1

2

3

4

5

6

7

8

9

10

@WebService(portName="AirportMgr",serviceName="ManagersRPCLit")

@SOAPBinding(style=Style.RPC,parameterStyle=ParameterStyle.WRAPPED,use=Use.LITERAL)public class RPCLiteralAirportManager {

@WebMethodpublic long

addAirport(@WebParam(name="code") String code,@WebParam(name="name") String name) {


RPC/literal StylePros and Cons

• Advantages:

> Simple, readable WSDL> SOAP message encodes operation and its parameters> no redundant type information

> WS-I compliant

• Disadvantages:

> SOAP messages cannot be validated against schemas


Document Style

• Every message should contain a single part

• Every part is defined by an element in the XMLschema defined within the WSDL file:

> Since there is a single element for a single part for eachinput message, function calls end up modelled asrequiring a single (object) parameter.

• No predefined or expected structure to the elementassociated with each message.


Document Style<portType>

1

2

3

4

5

6

7

8

9

10

<portType name="DocumentLiteralAirportManager"><operation name="addAirport">

<input message="tns:addAirport"/></input><output message="tns:addAirportResponse"/>

</operation><operation name="findNeighbors">

<input message="tns:findNeighbors/"><output

message="tns:findNeighborsResponse"/></operation></portType>



Document Style<message>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

<message name="addAirport"><part name="airport"

element="tns:airport"/></message><message name="addAirportResponse">

<part name="addAirportResponse"element="tns:addAirportResp

onse"/></message><message name="findNeighbors">

<part name="code" element="tns:code"/></message><message name="findNeighborsResponse">

<part name="findNeighborsResponse"element="tns:findNeighborsResp

onse"/></message>


Document Style<schema>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

<xs:element name="addAirportResponse" type="xs:long"/><xs:element name="airport" nillable="true"

type="tns:airport"/><xs:element name="code" nillable="true" type="xs:string"/><xs:element name="findNeighborsResponse" nillable="true"

type="ns1:stringArray"/><xs:complexType name="airport">

<xs:complexContent><xs:sequence>

<xs:element name="code" type="xs:string" minOccurs="0"/><xs:element name="name" type="xs:string" minOccurs="0"/>

</xs:sequence></

xs:complexContent></xs:complexType>


Document Style<binding>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

<binding name="AirportMgrBinding"type="tns:DocumentLiteralAirportManager">

<soap:binding style="document"transport="http://schemas.xmlsoap.org/soap/

http"/><operation name="addAirport"><soap:operation soapAction=""/><input><soap:body use ="literal"/></input><output><soap:body use ="literal"/></output>

</operation><operation name="findNeighbors">

<soap:operation soapAction=""/><input><soap:body use="literal"/></input>

<output><soap:body use ="literal"/></output></operation>

</binding>


Document StyleSample Message

1

2

3

4

5

6

7

8

9

10


<S:Header/><S:Body>

<ser:airport><code>LGA</code>

<name>New York La Guardia Airport</name></ser:airport> </S:Body>

</S:Envelope>

• What is the request?


Document/literal StyleJava-to-WSDL Specification

1

2

3

4

5

6

7

8

9

10

@WebService(portName="DocLiteralAirportMgr",serviceName="ManagersDoc")

@SOAPBinding(style=Style.DOCUMENT,parameterStyle =ParameterStyle.BARE,

use=Use.LITERAL)public class DocumentLiteralAirportManager {

@WebMethodpublic long

addAirport(@WebParam(name="airport")Airport airport ) {


Document/literal StylePros and Cons

• Advantages:

> Validate SOAP messages against XML schema> No redundant type information

> Mostly WS-I compliant

• Disadvantages:

> Somewhat complex WSDL> SOAP message does not encode operation, which makes

dispatching harder> Multiple children to SOAP body violates WS-I


Document "Wrapped" Style

• Every message must contain a single part

• Each part is defined by an element in the XMLschema defined within the WSDL file:

> the root element associated with the input message isnamed to match the function to be called.

> parameters to the function call are mapped to children ofthe root element associated with the input message.

> return values from the function call are mapped to childrenof the root element associated with the output message

• This style explicitly builds a representation similarto that used by the RPC/literal style.


Using the Document "Wrapped" Style

• <portType> and <message> definitions look justlike those for the Document/literal style

• Schema structure is richer:

> root element for message corresponds to function call> parameters to call are explicitly listed as children of the

root function call node.


Document "Wrapped" Style<message>

1<message name="addAirport">

2<part name="parameters"

3element="tns:addAirport"/>

4</message>

5<message name="addAirportResponse">

6<part name="parameters"

7element="tns:addAirportResponse"/>

8</message>


Document "Wrapped" Style<schema>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

<xs:element name="addAirport" type="tns:addAirport"/><xs:element name="addAirportResponse"

type="tns:addAirportResponse"/><xs:complexType name="addAirport">

<xs:sequence><xs:element name="code" type="xs:string" minOccurs="0"/>

<xs:element name="name" type="xs:string" minOccurs="0"/></xs:sequence>

</xs:complexType><xs:complexType name="addAirportResponse">




Document "Wrapped" Style<binding>

1

2

3

4

5

6

7

8

9

10

11

12

13

<binding name="WrappedAirportManagerPortBinding"type="tns:AirportManager">

<soap:binding style="document"transport="http://schemas.xmlsoap.org/soap/

http"/><jaxws:bindingsxmlns:jaxws="http://java.sun.com/xml/ns/jaxws"><jaxws:enableWrapperStyle>true</jaxws:enableWrapperStyle>

</jaxws:bindings><operation name="addAirport">

<soap:operation soapAction=""/><input><soap:body use="literal"/></input>

<output><soap:body use="literal"/></output></operation>


Document "Wrapped" StyleSample Message

1

2

3

4

5

6

7

8

9

10


<S:Header/><S:Body>

<ser:addAirport><code>JFK</code>

<name>New York Kennedy Airport</name></ser:addAirport></S:Body>

</S:Envelope>


Document/literal "Wrapped" StyleJava-to-WSDL Specification

1@WebService


3public long



6}


8// ...

It is the default style!


Document/literal "Wrapped" StylePros and Cons

• Advantages:

> SOAP message encodes operation and its parameters> Validate SOAP messages against XML schema> No redundant type information

> WS-I compliant

• Disadvantages:

> Very complex WSDL


WSDL 1.0 vs WSDL 2.0

http://upload.wikimedia.org/wikipedia/commons/c/c2/WSDL_11vs20.pngDWS-4050-EE6 - Developing Web Services with Java™ Technology

Copyright 2010 Sun Microsystems, Inc. All Rights Reserved. Revision A.0 SOAP and WSDL 3 - 44

Changes in WSDL 2.0

• Adding further semantics to the descriptionlanguage

• Removal of message constructs

• No support for operator overloading

• portType renamed to interface• Port renamed to endpoint


developing web services with java ™ technology dws-4050-ee6 revision a.0

Documents

web services w web services

web services slide

restful web services

web services frameworks

services e

java technology copyright

java technology dws

java technology introduction