Web Services for Java Developers

1
Web Services for Java Developers

• SOAP which leaves you smelling all service-like

2
Who are you?

• Dan Diephouse (dan_at_netzooid.com)
• Day job consists of running a logistics software
  business and consulting
• Pet WS Project XFire SOAP toolkit
  (http//xfire.codehaus.org)

3
Questions, questions, questions

• Why web services?
• How do I implement and design web services?
• What are all these different web services
  technologies?
• How do I build better web services?
• How do I integrate my services?

4
Goals

• Answer the questions on the previous slides
• Give a good mix of practical hands on knowledge
  with higher level design issues

5
Agenda

• Introduction to web services
• Web service design and best practices
• Toolkit Review
• Debugging, testing, and performance
• WS-
• Service Design Process
• Integration (SOA ESBs)

6
Code for this presentation

• Download the code
• http//netzooid.com/jia/code.zip
• http//netzooid.com/jia/jia.ppt

7
Introduction to Web Services

• Why oh why?
• XML Schema
• SOAP
• WSDL

8
Why Web Services? (Technical)

• XML is the universal language
• RMI cant really talk to .NET
• Interoperability
• More agile development

9
Why Web Services? (Business)

• Create tight integration between consumers and
  your service
• You create convenience for your consumer
• Tight integration may make it hard for them to
  switch
• Consumers may find uses for your service that
  you
• Dont have time to explore
• Didnt think to explore
• Example 40 of EBays sales happen over its API

10
Why SOAP services?

• Sophisticated tools to consume these services in
  every language
• Well see an example later on
• With large APIs, REST/HTTP services become hard
  to consume (IMHO!)
• SOAP works over any transport, not just HTTP

11
SOAP Basics

• XML Schema describes the messages
• WSDL describes the services operations
• SOAP provides the packaging to send messages
• Well cover the basics of each before exploring
  service creation and design

12
XML Schema

• Way to express XML structure
• A valid document conforms to a particular schema

ltxsdschema xmlnsxsdhttp//www.w3.org/2001/XMLSc
hema targetNamespacehttp//acme.com/foogt
lt/xsdschemagt
13
Simple Types

• XML Schema includes several simple types
• xsdouble
• xsint
• xsdecimal
• xsGMonth
• Etc
• You can extend and redefine these, as well as
  create your own

14
Simple Type Examples
ltCountgt5lt/Countgt ltMonthgt10lt/Countgt ltDepartureDategt
lt/DepartureDategt
ltxsdschema xmlnsxsdhttp//www.w3.org/2001/XMLS
chema targetNamespacehttp//acme.com/foo
elementFormDefaultunqalifiedgt ltxsdelement
nameSize typexsdint/gt ltxsdelement
nameMonth typexsdGMonth/gt ltxsdelement
nameDepartureDate
typexsddate/gt lt/xsdschemagt
15
Complex Types
ltdeveloper countryUSgt ltnamegtDan
Diephouselt/namegt ltrolegtCode Monkeylt/rolegt lt/deve
lopergt
ltxsdelement namedevelopergt
ltxsdcomplexTypegt ltxsdsequencegt
ltxsdelement namename typexsdstring/gt
ltxsdelement namerole typexsdstring/gt
lt/xsdsequencegt ltxsdattribute namecountry
typexsdstring/gt lt/xsdcomplexTypegt lt/xsdelem
entgt
16
Abstract Complex Types

• Allows a measure of reuse

ltxsdschema gt ltxsdelement namedeveloper
typedeveloperTypegt ltxsdcomplexType
namedeveloperTypegt ltxsdsequencegt
ltxsdelement namename typexsdstring/gt
ltxsdelement namerole typexsdstring/gt
lt/xsdsequencegt lt/xsdcomplexTypegt lt/xsdschemagt
17
Restrictions
ltxsdattribute namecountrygt ltxsdsimpleTypegt
ltxsdrestriction basexsdstringgt
ltxsdenumeration valueUnited States/gt
ltxsdenumeration valueCanadia/gt
lt/xsdsimpleTypegt lt/xsdelementgt
18
What is SOAP?
ltenvEnvelope xmlnsenv"http//www.w3.org/2003/05
/soap-envelope"gt ltenvHeadergt ltnalertcontrol
xmlnsn"http//example.org/alertcontrol"gt
ltnprioritygt1lt/nprioritygt ltnexpiresgt2001-06-2
2T140000-0500lt/nexpiresgt lt/nalertcontrolgt
lt/envHeadergt ltenvBodygt ltmalert
xmlnsm"http//example.org/alert"gt
ltmmsggtPick up Mary at school at 2pmlt/mmsggt
lt/malertgt lt/envBodygt lt/envEnvelopegt
19
SOAP Properties

• Its just XML (kinda)
• It cant contain PIs or DTDs
• Body Contains a message to the SOAP endpoint
  (ultimate recipient)

20
Headers

• Extensible location. Often used for
• Authentication Tokens
• Transactions
• Metadata about where the message is going to
• MustUnderstand attribute - if receiver does not
  understand the header, then it must throw a
  fault.
• Role attribute Says which intermediary the
  Header is destined for

21
SOAP Properties

• Transport Neutral.
• Runs over things named with capital letters
  HTTP, SMTP, JMS, XMPP, TCP, UDP, JXTA

22
Its not my fault

• The exceptions of SOAP

ltenvEnvelope xmlnsenv"http//www.w3.org/2003/05
/soap-envelope"gt ltenvBodygt ltenvFaultgt
ltfaultcodegtenvMustUnderstandlt/faultcodegt
ltfaultstringgtHeader was not understoodlt/faultstrin
ggt lt/envFaultgt lt/envEnvelopegt
23
Faults

• Contain fault code, message, role, and detail
  elements
• Fault code A general fault code Server,
  MustUnderstand, Version mismatch, etc.
• SOAP 1.2 includes an additional SubCode field
  which can be used for application specific error
  codes.
• Detail place for arbitrary XML which can contain
  application specific error codes

24
RPC Encoding

• Portion of the SOAP specs which specify an xml
  encoding
• Written because
• XML Schema spec wasnt finished at the time
• Needed a way to allow circular object graphs
• Ambiguous part of the spec that caused a lot of
  interoperability problems
• Just dont use it (more on this later)

25
RPC-Encoding Example
lteBookgt   lttitlegtMy Life and Worklt/titlegt   ltau
thor href"Person-1"/gtlt/eBookgtltePerson id"Pe
rson-1"gt   ltnamegtHenry Fordlt/namegt   ltaddress hr
ef"Address-2"/gtlt/ePersongtlteAddress id"Addre
ss-2"gt   ltemailgtmailtohenryford_at_hotmail.comlt/ema
ilgt   ltwebgthttp//www.henryford.comlt/webgtlt/eAdd
ressgt
26
SOAP Versions

• 1.1
• Everyone uses and supports it
• 1.2
• Being used more and more
• RPC-encoding is no longer required to be
  compliant
• Fault code is a QName
• Allows fault subcodes
• More...

27
WSDL

• Web Service Description Language
• Describes your service, its location and its
  operations
• Two flavors
• 1.1 Widely used
• 2.0 In process, much clearer application of
  concepts

28
Components in WSDL 1.1

• Types holds the XML Schema
• Messages Messages which are sent as part of
  operations
• Port Type the service interface
• Specifies operations
• Binding Binds a port type to a particular
  transport
• Service Describes the location of a binding

29
Component XML pieces
ltwsdlgt lttypes/gt? ltmessage/gt ltportType/gt
ltbinding/gt ltservice/gt lt/wsdlgt
30
Walkthrough Book Service

• Well write a service description to gain an
  understanding of the concepts
• Book price service
• One operation getPrice - which returns the
  price for an ISBN

31
PortType Your Interface
ltportType name"BookPrice"gt ltoperation
name"getBookPrice"gt ltinput name"isbn
message"aGetBookPriceRequest"/gt
ltoutput name"price
message"aGetBookPriceResponse"/gt
lt/operationgt lt/portTypegt
32
Messages
ltmessage name"GetBookPriceRequest"gt ltpart
name"isbn" type"xsstring" /gt lt/messagegt ltmessa
ge name"GetBookPriceResponse"gt ltpart
name"price" element"aBook"/gt lt/messagegt
33
XML Schema Types
lttypesgt ltxsschema targetNamespace"http//www.a
cme.com/BookQuote"gt ltxselement name"Book"gt
ltxscomplexTypegt ltxssequencegt
ltxselement name"Title" type"xsstring"/gt
ltxselement name"Author"
type"xsstring"/gt ltxselement
namePrice typexsdecimal/gt
lt/xssequencegt lt/xscomplexTypegt
lt/xselementgt lt/xsschemagt lt/typesgt
34
Binding Concrete Implementation
ltbinding name"BookPriceBinding"
type"aBookQuote"gt ltsoapbinding
style"document" transport"http//schemas.xm
lsoap.org/soap/http"/gt ltoperation
name"getBookPrice"gt ltsoapoperation
soapAction""/gt ltinputgt ltsoapbindbody
use"literal" namespace"http//www.acme
.com/BookQuote"/gt lt/inputgt ltoutputgt
ltsoapbindbody use"literal"
namespace"http//www.acme.com/BookQuote"/gt
lt/outputgt lt/operationgt lt/bindinggt
35
Sidenote Encoding and Style

• How many ways are there to send an XML message?
• 4ish
• Encoding literal vs. encoded (covered earlier)
• Style document, rpc, wrapped

36
Style

• RPC ltoperationgt element is implied, the toolkit
  needs to create it even though its not in the
  schema
• Document Follow the schema exactly.
• Wrapped A type of document style which puts the
  operation name in the schema
• Microsoft pioneered this style which is a simple
  convenience for the developer

37
Wrapped Schema Example
ltxselement namegetBookPrice"gt
ltxscomplexTypegt ltxssequencegt
ltxselement nameisbn typexsstring/gt
lt/xssequencegt lt/xscomplexTypegt lt/xselementgt lt
xselement namegetBookPriceResponse"gt
ltxscomplexTypegt ltxssequencegt
ltxselement reftnsBook"/gt lt/xssequencegt
lt/xscomplexTypegt lt/xselementgt
38
Which Operation??

• Document/Wrapped Operations are inferred from
  the XML types and the number of elements in the
  Body
• RPC ltgetFoogt is translated into getFoo
  operation
• WS-Addressing can also be used (more later)

39
Service
ltservice name"BookPriceService"gt ltport
name"BookPrice_Port" binding"aBookPric
eBinding"gt ltsoapaddress
location"http//acme.com/foo/BookPrice"/gt
lt/portgt lt/servicegt
40
Service in Action Request
ltenvEnvelope xmlnsenv"http//schemas.xmlsoap.or
g/soap/envelope/"gt ltenvBody xmlnsa"http//www.
acme.com/BookQuote"gt ltaisbngt0123456789lt/aisbngt
lt/envBodygt lt/envEnvelopegt
41
Service in Action Response
ltenvEnvelope xmlnsenv"http//schemas.xmlsoap.
org/soap/envelope/"gt ltenvBody
xmlnsa"http//www.acme.com/BookQuote"gt
ltaBookgt ltaTitlegtWeb Services for Java
Developerslt/aTitlegt ltaAuthorgtDan
Diephouselt/aAuthorgt ltaPricegt19.95lt/aPricegt
lt/aBookgt lt/envBodygt lt/envEnvelopegt
42
Wrapped Example Request
ltenvEnvelope xmlnsenv"http//schemas.xmlsoap.
org/soap/envelope/"gt ltenvBody
xmlnsa"http//www.acme.com/BookQuote"gt
ltagetBookPricegt ltaisbngt0123456789lt/aisbngt
lt/agetBookPricegt lt/envBodygt lt/envEnvelopegt
43
Wrapped Example Response
ltenvEnvelope xmlnsenv"http//schemas.xmlsoap.or
g/soap/envelope/"gt ltenvBody xmlnsa"http//www
.acme.com/BookQuote"gt ltagetBookPriceResponsegt
ltaBookgt ltaTitlegtWeb Services for
Java Developerslt/aTitlegt
ltaAuthorgtDan Diephouselt/aAuthorgt
ltaPricegt19.95lt/aPricegt lt/aBookgt
lt/agetBookPriceResponsegt lt/envBodygt lt/envEnve
lopegt
44
WSDL and Faults

• Just like you can declare exceptions with Java
  you can declare Faults with WSDL
• Custom faults declare one element in the schema
  that will provide more information to the
  consumer
• Lets retrofit our book service to throw an
  InvalidISBN fault

45
PortType
ltportType name"BookPrice"gt ltoperation
name"getBookPrice"gt ltinput name"isbn"
message"aGetBookPriceRequest"/gt ltoutput
name"price" message"aGetBookPriceR
esponse"/gt ltfault name"InvalidISBNFault"
message"aInvalidISBNFault"/gt
lt/operationgt lt/portTypegt
46
Messages
ltmessage name"GetBookPriceRequest"gt ltpart
name"isbn" type"xsstring" /gt lt/messagegt
ltmessage name"GetBookPriceResponse"gt ltpart
name"price" element "aBook"/gt lt/messagegt ltmess
age name"InvalidISBNFault"gt ltpart
name"InvalidISBNFaultDetail" e
element"aInvalidISBNFaultDetail"/gt lt/messagegt
47
XML Schema
ltxselement name"InvalidISBNFaultDetail"gt
ltxscomplexTypegt ltxssequencegt
ltxselement name"invalid-isbn"
type"xsstring"/gt lt/xssequencegt
lt/xscomplexTypegt lt/xselementgt
48
Binding
ltbinding name"BookPriceBinding"
type"aBookQuote"gt ltsoapbinding
style"document" transport"http//schemas.xmlsoap
.org/soap/http"/gt ltoperation name"getBookPrice"
gt ltsoapoperation soapAction""/gt
ltfault name"InvalidISBNFault"gt ltsoapfault
name"InvalidISBNFault"
use"literal"/gt lt/faultgt lt/operationgt lt/bind
inggt
49
Fault Example
ltenvEnvelope xmlnsenv"http//schemas.xmlsoap.or
g/soap/envelope/"gt ltenvBody xmlnsa"http//www.
acme.com/BookQuote"gt ltenvFaultgt
ltfaultcodegtenvClientlt/faultcodegt
ltfaultstringgt "" is an invalid ISBN
character lt/faultstringgt ltdetailgt
ltaInvalidISBNFaultDetailgt
ltinvalid-isbngt123lt/invalid-isbngt
lt/aInvalidISBNFaultDetailgt lt/detailgt
lt/envFaultgt lt/envBodygt lt/envEnvelopegt
50
WSDL 1.1 vs 2.0

• portType renamed interface
• 2.0 has better MEP support
• 2.0 is not widely supported yet
• If you dont know why you should be using it,
  then you shouldnt be (yet)

51
Basic Profile

• Basic Profile http//ws-i.org
• Tries to make ambiguous parts of the WSDL/SOAP
  specs unambiguous.
• Versions 1.0/1.1
• Well talk about portions as we move through the
  session

52
Designing Services

• So much XML! Wheres the Java???

53
Design Services Breakdown

• Coding services
• POJOs and JSR 181
• XMLBeans (Schema)
• WSDL-gtService
• Interop issues will be interspersed
• Schema Design
• Extensibility
• Break
• Versioning

54
Your First Service POJOs and JSR 181

• POJOs are the language of a Java Developer
• The idea use POJOs as Data Transfer Objects
  (DTO). Bind them to XML and generate an XML
  schema automatically
• JSR 181 provides annotations for web services
  (more in a minute)

55
A Birds Eye View
The Toolkit Generates XSD WSDL, binds XML
Service and DTOs Converts back and forth between
your internal API and the web service.
Your API Business Logic
56
Why Not This?
The Toolkit Generates XSD WSDL, binds XML
Your API Business Logic
57
Data Transfer Objects (DTOs)

• Exposing your core business classes is bad
• Often contains things irrelevant to end user
• Often contains things you dont want the end user
  to have access to
• If you change your internal API, your external
  API (the web service) changes too. Bad for
  backward compatability
• DTOs are used as a wrapper around your core logic
• Used to expose functionality to the consumer

58
Our Service

• Were going to create a Purchase Order service
• We want to
• Receive purchase orders
• Retreive purchase orders
• Get a list of recent purchase orders

59
Step 1 Create our service class
60
public interface OrderService _at_WebMethod
_at_WebResult(name "purchaseOrderId") long
receiveOrder( _at_WebParam(name
"purchaseOrder") PurchaseOrder
order) throws XFireFault
_at_WebResult(name "purchaseOrder")
PurchaseOrder getPurchaseOrder(
_at_WebParam(name "purchaseOrderId")
long id) throws XFireFault _at_WebResult(name
"purchaseOrders") CollectionltPurchaseOrdergt
getRecentOrders() throws XFireFault
61
Whats in a service class..

• One method for each operation
• Exceptions Instead of just throwing
  NoSuchOrderException, well catch our internal
  exceptions and create the appropriate fault info.
• Annotations

62
JSR 181 Annotations

• Annotate classes with web service specific data
• _at_WebMethod
• _at_WebParam
• Java doesnt store the name of method parameters,
  so we need to provide it _at_WebParam(namefoo)
• _at_WebResult like _at_WebParam, but for results

63
Step 2 Create the implementation
_at_WebService(endpointInterface"com.acme.code.Order
Service") public class OrderServiceImpl
implements OrderService

• _at_WebService demarcates a class as a web service
• endpointInterface specifies the interface to
  generate the port type against

64
Step 3 Create Your DTOs
public class PurchaseOrder private Address
shipTo private Address billTo private
String comment private ListltItemgt items
private long purchaseOrderId . .
65
Step 4 Deploy!

• Deploying is different with every toolkit
• Typically with HTTP you register a servlet and
  there is a configuration mechanism
• To the web browser.

66
Step 5 Create a client

• Users can use the WSDL to
• Generate classes to access your service
• Dynamically access your service
• Lets take a look at using .NET

67
Accessing with .NET

• And were off to Visual Studio momentarily

68
TCPMon Watching your Service

• TCPMon allows you to see your messages going
  across the wire
• java cp axis.jar org.apache.axis.utils.tcpmon

69
Our Request Part 1
ltsoapEnvelope xmlnssoap"http//schemas.xmlsoap.
org/soap/envelope/" xmlnsxsi"http//www.w3.org/2
001/XMLSchema-instance" xmlnsxsd"http//www.w3.o
rg/2001/XMLSchema"gt ltsoapBodygt
ltreceiveOrder xmlns"http//code.acme.com"gt
ltpurchaseOrdergt ltbillTogt
ltcitygtGrand Rapidslt/citygt
ltnamegtDan Diephouselt/namegt
ltstategtMIlt/stategt
ltstreetgt2032 Lake Drlt/streetgt
ltzipgt49506lt/zipgt lt/billTogt

70
Our Request Part 2
ltcomment xsinil"true" /gt
ltitemsgt ltItemgt
ltUSPricegt0lt/USPricegt
ltcomment xsinil"true" /gt
ltpartNumbergt123lt/partNumbergt
ltproductNamegtGood smelling SOAPlt/productNamegt
ltquantitygt0lt/quantitygt
ltshipDategt0001-01-01T000000lt/shipDat
egt lt/Itemgt
lt/itemsgt ltpurchaseOrderIdgt0lt/purcha
seOrderIdgt lt/purchaseOrdergt
lt/receiveOrdergt lt/soapBodygt
lt/soapEnvelope
71
Our Response
ltsoapEnvelope xmlnssoap"http//schemas.xmlso
ap.org/soap/envelope/"gt ltsoapBodygt
ltreceiveOrderResponse xmlns"http//code.acme.com"
gt ltpurchaseOrderIdgt5lt/purchaseO
rderIdgt lt/receiveOrderResponsegt
lt/soapBodygt lt/soapEnvelopegt
72
BP - Interopability nillable

• Example Schema
• ltelement nameDate nillabletrue
  typedateTime/gt
• Example XML
• ltDate xsiniltrue/gt
• What happens .NET or Java will barf if the the
  element is a value type

73
BP - Interoperability nillable

• Value types (int/long/etc) cannot be null
• Value types differ from language to language
• DateTime is a value type in .NET, but Date is not
  in Java
• Some toolkits (.NET 2.0, XMLBeans, etc) can
  handle this.
• Others (Axis 1.x, .NET 1.0) cannot

74
BP - Interopability nillable

• Be aware of what your toolkit is outputting in
  the schema
• Nillable will break on any sort of value type in
  any language
• BE AWARE that XML ! Java

75
BP - Style and Encoding

• If you have any doubt use literal encoding always
• Encoded use is kind of against the basic profile
• The wording is ambiguous
• Wrapped vs Document style its up to you.
• Document style has the connotations message
  passing which is what SOAP is all about

76
BP Faults

• Declare a fault in the WSDL for specific errors
  that you feel your consumers need to deal with
• Faults have faultcode, faultstring and faultactor
  fields. USE THEM

77
Toolkits

• JSR 181
• Axis Beehive WSM http//ws.apache.org/axis
• XFire http//xfire.codehaus.org
• Suns JAX-WS?
• POJO/XML Bindings
• Axiss internal type system - http//ws.apache.org
  /axis
• JAXB 1.1 2.0
• JiBX http//jibx.sourceforge.net
• XFires Aegis Binding http//xfire.codehaus.org

78
Service 2 Schema and XMLBeans

• Steps are basically the same as Service 1
• Instead of POJOs well use XMLBeans
• XMLBeans are classes generated from XML Schema

79
Step 1 Design the Schema
80
Step 2 Compile XMLBeans
ltjava classname"org.apache.xmlbeans.impl.tool.
SchemaCompiler" classpathref"xmlbeans.path"
fork"true"gt ltarg value"-d" /gt ltarg
valueoutputdir" /gt ltarg value"basedir/src/
schema" /gt lt/javagt
81
Step 3 Write the Service Class
public interface OrderService
PurchaseOrderIdDocument receiveOrder(
PurchaseOrderDocument purchaseOrder)
throws XFireFault PurchaseOrderDocument
getPurchaseOrder( PurchaseOrderIdDocum
ent id) throws XFireFault
CollectionltPurchaseOrderDocumentgt
getRecentOrders() throws XFireFault
82
Step 3 Write the Service Class
public PurchaseOrderIdDocument receiveOrder(
PurchaseOrderDocument purchaseOrder)
throws XFireFault PurchaseOrderType
order purchaseOrder.getPurchaseOrder()
order.setPurchaseOrderId(count)
PurchaseOrderIdDocument pid
PurchaseOrderIdDocument.Factory.newInstance()
pid.setPurchaseOrderId(order.getPurchaseOr
derId()) return pid
83
Step 4 Deploy
84
Step 5 Write the client
85
Some things to note

• Writing a schema really wasnt that hard
• You gained control and coherency at the expense
  of some up front thought and design time
• Reusability
• Our PurchaseOrderId type is reused for a more
  coherent and elegant schema
• XMLBeans is very XMLish, while retaining some
  sense of javaness

86
More on XMLBeans

• Can access the document at any time
• xmlBean.getDomNode()
• xmlBean.newXMLStreamReader()
• Etc
• Can modify the xml and have changes reflected in
  the bean and vise a versa

87
Schema-gtJava Toolkits

• Any JAX-RPC toolkit (i.e. Axis 1.x)
• Castor
• GLUE
• JiBX
• JAXB 1.1 2.0
• Systinet
• XMLBeans

88
Code first vs. schema first

• Schema first gives you a much more well defined
  contract
• Forces you to think in terms of XML and messages
  instead of objects, which is a Good Thing
• Not too much extra work

89
Service 3 WSDL-gtService

• Most toolkits actually require more than just a
  Schema the full WSDL
• Well look at using Axiss WSDL2Java tool to
  build a service

90
Step 1 Write the WSDL

• Use WSCF to create our WSDL via our schema
• Constructs WSDL an operation at a time
• Forces you to think about whats coming in and
  what is going out
• The WSDL is a CONTRACT. It must not break!

91
Step 2 Build service stubs

• WSDL2Java tool builds us our DTOs and a service
  stub which we can fill in
• java org.apache.axis.wsdl.WSDL2Java foo.wsdl

92
Joys of JAX-RPC

• OrderServiceInterface Service Interface
• OrderServiceImpl Our implementation
• DTOs are also generated
• Address
• PurchaseOrder
• etc

93
Step 3 Service Implementation
public class OrderServiceImpl implements
com.acme._2005._05.OrderServiceInterface
public com.acme.purchase_order._2005._08.Purch
aseOrderType getPurchaseOrder(long
purchaseOrderId) throws java.rmi.RemoteException
return null . .
94
Step 4 Deploy

• Axis uses a WSDD configuration syntax

ltdeployment xmlns"http//xml.apache.org/axis/w
sdd/" xmlnsjava"http//xml.apache.org/axis/wsdd
/providers/java"gt ltservice nameOrderService"
provider"javaRPC"gt ltparameter
name"className" valuecom.acme.OrderSer
vice"/gt ltparameter name"allowedMethods"
value""/gt lt/servicegt lt/deploymentgt
95
Schema Design

• No, you cant write web services just in Java.

96
The XML/Java Mismatch

• There is not an equivalent Java type for every
  XML type. Examples
• GMonth
• A Regex restriction
• PositiveInteger
• This applies to ALL Languages
• You need to be aware of your consumers
• Toolkits such as XMLBeans/JAXB 2.0/.NET 2.0 make
  great strides in this area

97
Think in Messages

• SOAP is asynchronous message passing
• SOAP is NOT serialized objects
• SOAP is NOT RMI
• Exceptions are NOT Faults
• Thinking otherwise will result in performance and
  design problems

98
Problem

• Sometimes I want a whole message
• Sometimes I want part of a message
• If I always send the whole message it results in
  latency and performance issues

99
Parameter Driven Messages

• Effective way to combat bandwith and latency
  issues
• Often messages contain many different chunks
• Specify parameters which tell the service whether
  or not the client needs the chunk
• Creates smaller messages, lower processing time,
  lower latency

100
Request 1
ltgetPurchaseOrdergt ltPurchaseOrderIdgt100lt/Purchas
eOrderIdgt ltRetrieveItemsgttruelt/RetrieveItemsgt lt/
getPurchaseOrdergt
101
Response 1
ltaPurchaseOrder xmlnsa"http//acme.com/purchase
Order/2005/08"gt ltaShipTogt...lt/aShipTogt
ltaBillTogt...lt/aBillTogt ltaItemsgt
ltaItemgt ltaProductNamegtACME
Explosiveslt/aProductNamegt
ltaQuantitygt1lt/aQuantitygt
ltaPartNumgtlt/aPartNumgt ltaUSPricegt999.99lt/a
USPricegt ltaShipDategt2005-08-13T102224.33
5-0400lt/aShipDategt lt/aItemgt
lt/aItemsgt lt/aPurchaseOrdergt
102
Request 2
ltgetPurchaseOrdergt ltPurchaseOrderIdgt100lt/Purchas
eOrderIdgt ltRetrieveItemsgtfalselt/RetrieveItemsgt lt
/getPurchaseOrdergt
103
Response 1
ltaPurchaseOrder xmlnsa"http//acme.com/purchase
Order/2005/08"gt ltaShipTogt...lt/aShipTogt
ltaBillTogt...lt/aBillTogt lt/aPurchaseOrdergt
104
Flattened Your Schema

• Dont reproduce fragments over and over
• Advantages
• Better structure
• Much more friendly to your end user
• Decreased bandwidth

105
Bad Example
ltProjectsgt ltProjectgt ltNamegtOperation
Foolt/Namegt ltEmployeegt ltNamegtDan
Diephouselt/Namegt ltTitlegtWeb Services
Developerlt/Titlegt lt/Employeegt ltEmployeegt
ltNamegtJames Bondlt/Namegt ltTitlegtSecret
Agentlt/Titlegt lt/Employeegt lt/Projectgt
ltProjectgt ltNamegtOperation Barlt/Namegt
ltEmployeegt ltNamegtJames Bondlt/Namegt
ltTitlegtSecret Agentlt/Titlegt lt/Employeegt
lt/Projectgt lt/Projectsgt
Replication!
106
Good Example
ltProjectInfogt ltProjectgt ltNamegtOperation
Foolt/Namegt ltEmployee id"1"/gt ltEmployee
id"2"/gt lt/Projectgt ltProjectgt
ltNamegtOperation Barlt/Namegt ltEmployee
id"2"/gt lt/Projectgt ltEmployee id1gt
ltNamegtDan Diephouselt/Namegt ltTitlegtWeb
Services Developerlt/Titlegt lt/Employeegt
ltEmployee id2gt ltNamegtJames Bondlt/Namegt
ltTitlegtSecret Agentlt/Titlegt lt/Employeegt lt/Projec
tInfogt
107
Namespace Versioning

• How do I determine which version an XML document
  is?
• Anytime you make a change to your schema which
  isnt backward compatible, change your namespace
  version

108
Namespace Versioning

• Examples
• http//acme.com/purchase-order/2005/08
• http//acme.com/purchase-order/2005/11
• urnacme-compurchase-order200508

109
Namespace Versioning

• Example in eclipse

public interface OrderService _at_WebMethod
_at_WebResult(name "purchaseOrderId") long
receiveOrder( _at_WebParam(name
"purchaseOrder") PurchaseOrder
order) throws XFireFault
_at_WebResult(name "purchaseOrder")
PurchaseOrder getPurchaseOrder(
_at_WebParam(name "purchaseOrderId")
long id) throws XFireFault _at_WebResult(name
"purchaseOrders") CollectionltPurchaseOrdergt
getRecentOrders() throws XFireFault
110
Making your schema Extensible

• What happens if you want to add an element or
  attribute later?
• ltxsdsequencegt only allows declared elements
• Future documents would no longer be valid
• Need wildcard to allow anything

111
Extensibility and Enums

• No equivalent of xsanyType with enumerations
• Therefore, if you add things to a schema enum, it
  must be a new version

112
Schema Code Conventions

• complexTypes are often named FooType instead of
  Foo
• Be nice to your consumers and use documentation
  annotations

113
Handling binary data inline it

• xsdbyte
• Base64 encodes data
• 30 increase in size
• Easy to use
• Doesnt work if you cant fit data from all
  requests in memory

114
Handling binary data Attachments

• Soap w/ Attachments outlines way to attach binary
  data via MIME attachments
• Must be Base 64 encoded

115
Handling binary data MTOM

• An optimized way of handling binary attachments
• SOAP envelope is MIME root
• Each attachment is another MIME element
• Doesnt require you to base64 encode

116
Handling binary data Dont send it

• Send a URL which specifies where to get the
  resources
• This is used by Amazon and other
• Example album clip art
• ltImageURLgthttp//amazon.com/../foo.jpglt/ImageURLgt

117
Using Relax NG

• Relax NG is an XML Schema alternative that many
  find more intuitive
• You can develop in RNG and convert to XML Schema

118
Break sponsored by
119
Versioning Tactics
120
Why Versioning is an Issue

• Obviously, you need to be able to update and
  change your API
• Causes problems
• Maintenance increases for each version
• Code bloat
• No good way to map multiple sets of XML to a
  single set of objects

121
Sidenote Schema Maintenance

• If every division has their own schema, your
  maintenance costs are going to grow exponentially
  (n2)
• Itll be worth the effort to get different
  divisions to agree on a schema and maintain them
  centrally
• If youre exposing your services outside your
  organization, this isnt as big of an issue

122
Unified DTO pattern

• Maps arbitrary XML forms to the same set of
  objects
• Very few toolkits support this
• JiBX http//jibx.sf.net
• Impossible with Annotations

123
Multiple DTO pattern

• DTO layer between your service and the world

DTO v1
Your API
Service Router
DTO v2
124
Service Routing

• Youll need a way to determine which service you
  want to invoke
• Methods
• Endpoint
• Header
• Namespace

125
Routing Endpoint

• Create different endpoints for each service
  version
• http//localhost/OrderService/v1
• http//localhost/OrderService/v2

126
Routing Header

• Version Header (EBay does this)
• ltVersiongt341lt/Versiongt
• You can create interceptors which route the
  message to the appropriate service based on this
  header

127
Routing Namespace

• Create a Map between namespace versions and the
  appropriate service to invoke
• Namespace urnpurchase-order200508 goes to
  implementation 1
• Use an interceptor to handle this routing

128
Transformations

• Keep one service which is the current version
• Use XSLT to transform messages between different
  versions
• Can get complicated depending on how many service
  versions you have and your XSLT experience

129
Deployment Versioning

• Database becomes ultimate authority
• New endpoint for each version
• If your database changes singificantly, this
  fails.

http//.../v2
http//.../v1
Application 1.0
Application 2.0
Database
130
Web Service Toolkits
131
Choosing a databinding API

• Your application requirements will help determine
  the databinding or lack there of
• XML APIs
• SAX, DOM, StAX
• Databinding
• JAXB, XMLBeans, JAX-RPC 1.1, JiBX, Castor
• Depends on your versioning, performance and time
  requirements

132
XML SAX StAX

• Why
• Low memory
• Fast
• When
• You have very contstrained memory requirements
• You are writing your own databinding

133
StAX Example
int event reader.getEventType() while (
reader.hasNext() ) switch( event )
case XMLStreamConstants.START_ELEMENT
QName name reader.getName() case
XMLStreamConstants.END_ELEMENT case
XMLStreamConstants.CHARACTERS // can
read characters as stream or string default
break event
reader.next()
134
XML DOM

• Why Easy API to work with XML
• When
• You want random access to the document you are
  receiving
• WS-Security (and other specs) requires DOM model
• Memory isnt a big issue

135
XML Which DOM?

• W3C DOM
• Pros in every JDK
• Cons Bad API, Crapshoot as to how it will work
  on different JDKs
• XOM Great API, fast, low memory for DOM, LGPL
• DOM4J OK API, moderately fast, ASL
• JDOM OK API, moderately fast

136
JAXB

• Medium performance
• New set of DTOs for each version
• When
• You want to bind your XML to a very POJO like
  structure
• Youre using JAX-WS

137
XMLBeans

• Medium performance
• New set of DTOs for each version
• When You want a very XMLish API. Can access DOM
  at any time

138
JiBX

• Fastest databinding that I know of
• Unified DTO multiple DTO versions available
• When You want a very fast, Javaish databinding

139
Toolkits

• The Sun Way JAX-RPC 1.1, JAX-WS
• Alternative Axis, GLUE, WASP, XFire
• Roll-your-own Listen on HTTP, process

140
The Truth about Toolkits

• It matters, but
• More important is
• Good design principles
• Using the correct databinding API
• Good web services are hard period (but getting
  easier)

141
JAX-RPC

• JAX-RPC 1.1 is just BAD
• Very RPC oriented
• Developer unfriendly
• W3C DOM based

142
JAX-WS

• Looking good, but not out yet
• Handler concept from JAX-RPC
• Based on much more WSDLish concepts, and less
  RPCish concepts

143
Axis 1.X

• Open source
• Very interoperable
• Supports RPC-Encoding if you need it
• SLOW Memory intensive
• Hard to use
• SAX/DOM based
• Databinding JAX-RPC style, XMLBeans

144
Axis 2

• Rework of Axis 1 based on StAX
• Still in progress 0.9x release
• Databinding
• AXIOM is a StAX based parser that can cache nodes
  in a tree if need be
• Will (soon?) support JiBX/XMLBeans in addition

145
GLUE

• Very interoperable
• Easy to use
• Databinding based on Electric XML (DOM)

146
WASP/Systinet

• Very good toolkit
• Cost is of revenue (hard to determine)
• Databinding its very own

147
XFire

• Fast
• Embeddable
• Easy to use
• Open Source
• Low on the WS- support
• Databinding JAXB, JiBX (soon), XMLBeans, XOM and
  Aegis bindings

148
The Real Reason to use XFire

• Hani Suleiman uses it
• (and hasnt biled it)
• (yet)

149
Roll Your Own

• Just dont
• Spec is big, all sorts of minor issues which
  could come up

150
Testing and Debugging
151
TCPMon

• We saw this in action earlier
• Very easy to use and free (http//ws.apache.org/ax
  is)
• Doesnt tell you what went wrong, you still need
  to figure it out

152
Mindreefs SOAP Scope

• The BEST tool for debugging everything to do with
  web services
• Will tell you whats wrong with your WSDL, schema
  or messages

153
Unit Testing

• You test your code, you should test your services
  as well
• How do you test against .NET without complicated
  set up?
• Answer Capture messages and resend in your unit
  tests

154
Unit Test example from XFire

• Send the document
• If there is a response, run XPath assertions to
  test for the correct results.
• What you should test
• Response values and structure
• Faults are sent in appropriate cases (i.e. Bad
  login)

155
Unit Test example from XFire
Document response invokeService("Test",
"/org/your/classpath/Message1.xml")
addNamespace("test", "urnTest")
assertInvalid("//sFault") assertValid("//test
Response", response) assertValid("//testRespons
etext()'howdy'", response)
156
Performance
157
Performance

• Web services have high latency and high bandwidth
  due to XML
• Large documents may not fit in memory

158
Caching

• Why reconstruct the purchase order document for
  every request?
• Create an interceptor which stores the document
• If the incoming request meets certain
  requirements, resend stored request

159
Memory

• StAX and SAX allow you to parse documents
  incrementally
• StAX Streaming API for XML. Allows you to work
  with documents in a pull fashion
• Axis 2 and XFire are both built on this model

160
Working with large documents

• Possible to work with objects in low memory
• JiBX allows you to do this easily by iterating
  over document portions

ctx.parsePastStartTag("element namespace",
"element name") while (!ctx.isEnd()) Object
obj ctx.unmarshalElement() // do whatever
you want with the unmarshalled element ctx.parse
PastEndTag()
161
Latency

• The biggest problem with XML is latency since
  parsing text takes time
• Reduce document size as much as possible
• Remember parameter driven design?
• Reduce the number of messages that need to be
  sent
• Make sure you use a StAX toolkit
• Doesnt require a double transformation from
  InputStream to DOM to Objects
• You could use Binary XML

162
Caveat

• Good architecture and planning can help anything
  scale
• Some very very large corporations are running on
  Axis 1.x
• You will just need more hardware

163
Binary XML

• About 4-5 times faster than just regular XML
• Many different flavors
• Fast Infoset StAX driver available
  (http//fi.dev.java.net)
• Question If you control both endpoints why are
  you using XML?
• Make sense in an intermediary situation
• Or interdepartment communication where everyone
  agrees on a standard schema

164
WS-

• Navigating the landscape

165
WS-

• Term which refers to the proliferation of web
  service specifications
• Which ones are important?
• Which ones can I use?
• Answer it depends

166
WS-Addressing

• In protocols without URIs, how do we adress
  things?
• How do we do addressing in intermediary
  scenarios?
• How do we specify the action/operation we want to
  perform?

167
WS-Addressing Example
ltSHeader xmlnsS"http//www.w3.org/2003/05/soap-
envelope" xmlnswsa"http//schemas.xmlsoap.org/
ws/2004/08/addressing" xmlnsfabrikam"http//ww
w.fabrikam123.com/svc53"gt ltwsaMessageIDgtlt/wsa
MessageIDgt ltwsaRelatesTogtlt/wsaRelatesTogt
ltwsaTogthttp//business456.example/client1lt/wsaTo
gt ltwsaActiongthttp//fabrikam123.com/mail/Delete
Acklt/wsaActiongt ltwsaReplyTogt
ltwsaAddressgthttp//business456.example/client1lt/w
saAddressgt lt/wsaReplyTogt lt/SHeadergt
168
WS-Security

• Used to encrypt and verify messages or portions
  of messages
• Standard authentication tokens
• Why not encrypt at transport?
• SOAP messages may go through intermediaries

169
WS-Security

• Kind of hard to integrate
• Not supported by all clients
• .NET people can use Microsofts Web Services
  Extensions
• Axis people can use WSS4J
• WASP/GLUE have libraries they can use
• Greatly slows things down
• Use transport level encryption if possible

170
Reliability and Web Services

• How do you guarantee message delivery?
• (Shhhh HTTP isnt reliable!)

171
WS-RX

• WS-Reliability specifies a way to guarantee via a
  set of soap messages
• CreateSequence, Acknowledge messages
• Reality Its slow, high latency

172
SOAP over JMS

• Instead of WS-RX, use SOAP over JMS whenever
  possible
• JMS is crazy fast and very reliable
• Easy to configure and use
• When using with .NET or other platforms
• Create a JMS proxy in Java
• Use your JMS provider via IKVM

173
Service Design Process
174
Steps to a successful service

• Establish the scope of the service
• Identify consumers
• Determine anticipated usage
• Model the service
• Identify interaction scenarios
• Design the message structure

175
Establish Service Scope

• What is this service trying to accomplish
• Questions such as
• Are we providing read access? Write access?

176
Identify consumers

• Will this service be used internally, externally
  or both?
• What type of security do we need?
• Are the consumers competent in WS-?
• Do we anticipate future usage of this service by
  people outside the original target audience?

177
Determine anticipated usage

• Obviously you want to be able to handle the load
• Use appropriate technologies to achieve desired
  performance
• Determine hardware processing requirements
• What kind of latency will be appropriate?

178
Model the service

• Map out which operations your consumers will be
  performing
• Determine authentication mechanism

179
Identify interaction scenarios

• Dont try to be too flexible
• Identify what operations your users actually need
• Will users always need all the data from an
  operation?
• Will the never need all the data?
• Will different users need different Data?
• How will the service interact with your other
  services?

180
Design the message structure

• You should now have enough information to design
  your XML schemas

181
Purchase Order Example

• Our examples earlier were a bit contrived
• Lets go through and achieve a much better design

182
Establish Service Scope

• Were a provider of ACME Scented Soaps.
• We want our customers to be able to submit orders
  for our goods
• We should provide some kind of account history so
  they can view their transactions
• Well allow them to cancel order, but not revise
  them

183
Identify Consumers

• Off site customers, familiar with web services
• Customers are only in the US (for now)
• Use Java and .NET primarily
• Well need encryption HTTPS will suffice as
  there are no intermidiaries

184
Model the Service

• long pid submitOrder(PurchaseOrder order)
• void cancelOrder (long pid)
• ListltPurchaseOrdergt getOrders(Date start, Date
  end)

185
Identify Interaction Scenarios

• getOrders Do consumers really need all the data
  in the PurchaseOrder?
• We may want to add a ltRetrieveItemsgt parameter
  here
• We have no other services to worry about here
• If we add more later on itd be nice to have an
  authentication mechanism that worked for all of
  them

186
Design the Message Structure

• PurchaseOrder
• ShipTo
• BillTo
• Items
• BillTo/ShipTo Only need to handle US Adresses

187
Integration SOA ESBs

• Putting it all together

188
What is SOA?

• SOA Service oriented architecture
• Traditional Design an application, tack on a web
  service
• SOA Design application as a service

189
How?

• Youve already learned the basics
• Design good schemas
• Design good WSDLs
• Theyre your service CONTRACT

190
What is ESB?

• Depends on who you ask
• A message broker between a collection of services
• Provides routing, caching, security, reliability

191
What is JBI?

• The Java SOAESB Buzzword Compliant JSR
• Normalized Message Router
• JBI is a way to connect everything
• WSDL like
• Or for the cynical glorified SOAP over JMS

192
JBI the Acronym Collector

• XPATH
• XSLT
• SOAP
• WSDL
• JCA
• FTP
• HTTP
• JMS
• JMX

193
JBI Implementations

• ServiceMix http//servicemix.org
• Sun http//java.sun.com/integration

194
Audience Response

• Questions?