SOAP Protocol

1
SOAP Protocol

• Service Oriented Architecture Protocol
• Simple Object Access Protocol

2
W3C Web Service Definition

• A Web service is a software system designed to
  support interoperable machine-to-machine
  interaction over a network. It has an interface
  described in a machine-processable format
  (specifically WSDL). Other systems interact with
  the Web service in a manner prescribed by its
  description using SOAP-messages, typically
  conveyed using HTTP with an XML serialization in
  conjunction with other Web-related standards

3
SOAP History

• Microsoft begins investigating XML-based
  distributed computing in 1997
• Goal enable applications to communicate by
  Remote Procedure Calls (RPCs)
• Userland publishes a version of the SOAP
  specification in 1998 (XML-RPC)
• IBM supports SOAP 1.1 in 2000 and releases a Java
  Soap implementation
• SOAP 1.2 was a W3C recommendation in 2003

4
What is SOAP?

• Industrys best effort to standardize on an
  infrastructure for cross-platform XML distributed
  computing
• A mechanism for defining the unit of
  communication
• SOAP envelope that encloses everything
• A Body for the Message which can contain
  arbitrary XML information
• Headers that encapsulate information outside the
  body

5
What is SOAP?

• A processing model a set of rules for dealing
  with SOAP messages in software
• A mechanism for error handling Using SOAP
  faults, errors can be detected and diagnostic
  information can be exchanged between participants
• An extensibility model SOAP headers are used to
  create extensions on top of SOAP

6
What is SOAP?

• A flexible mechanism for data representation
  allows for the exchange of data already
  serialized in some format as well as a convention
  for representing programming language datatypes
  in XML
• A convention for RPCs and responses
• A protocol binding framework used to send SOAP
  messages across HTTP connections

7
Specification Structure

• Find the spec at http//www.w3.org/TR/SOAP
• Part 1, The Messaging Protocol foundation info
  (processing model, extensibility model, message
  structure)
• Part 2, Adjuncts extensions for
  proof-of-concept and to provide a baseline for
  functional interoperable services

8
SOAP Messaging Framework

• What does a message look like?
• This one is XML sent by HTTP
• POST /axis/InventoryCheck.jws HTTP/1.0
• Content-Tye application/soapxmlcharsetutf-8
• lt?xml version1.0encodingUTF-8?gt
• ltsoapenvEnvelope xmlnssoapenvhttp//www.w3.org
  /2003/05/soap-envelope
• xmlnsxsdhttp//www.w3.org/2001/XMLSchema
• xmlnsxsihttp//www.w3.org/2001/XMLSchema-ins
  tancegt
• ltsoapenvBodygt
• ltdoCheck soapenvencodingStylehttp//www.w3.o
  rg/2003/05/soap-encodinggt
• ltarg0 xsitypesoapencstring
• xmlnssoapenchttp//schemas.xmlsoa.org/s
  oap/encoding/gt947-TIlt/arg0gt
• ltarg1 xsitypesoapencint
• xmlnssoapenchttp//schemas.xmlsoa.org/s
  oap/encoding/gt3lt/arg0gt
• lt/doCheckgt
• lt/soapenvBodygt
• lt/soapenvEnvelopegt

9
Here is the Response

• Response delivered using HTTP
• Content-Tye application/soapxmlcharsetutf-8
• lt?xml version1.0encodingUTF-8?gt
• ltsoapenvEnvelope xmlnssoapenvhttp//www.w3.org
  /2003/05/soap-envelope
• xmlnsxsdhttp//www.w3.org/2001/XMLSchema
• xmlnsxsihttp//www.w3.org/2001/XMLSchema-ins
  tancegt
• ltsoapenvBodygt
• ltdoCheckResponse soapenvencodingStylehttp//
  www.w3.org/2003/05/soap-encodinggt
• ltrpcresult xmlnsrpchttp//www.w3.org/200
  3/05/soap-rpcgtreturnlt/rpcresultgt
• ltreturn xsitypexsdbooleangttruelt/returngt
• lt/doCheckResponsegt
• lt/soapenvBodygt
• lt/soapenvEnvelopegt

10
Vertical Extensibility

• Why use SOAP? Why not just use HTTP?
• Document can be extended using headers without
  changing the body
• Consider adding notary information to a purchase
  order
• ltpo id2352 submitted2004-01-05
  custID73852gt
• ltnotarytoken xmlnsnotaryhttp//notaries-r-u
  s.comgt XQ34Z-4G5
• lt/notarytokengt
• ltbillTogt lt/billTo
• lt/pogt

11
Repercussions

• Document schema would have to be extensible
• You and consumers would have to agree on how to
  process extensible parts of the document
• SOAP presents headers as an alternative to this
  technique

12
Headers

• The notary information is carried in the SOAP
  header as an extension
• ltsoapenvEnvelope xmlnssoapenvhttp//www.w3.org
  /2003/05/soap-envelopegt
• ltsoapenvHeadergt
• ltnotarytoken xmlnsnotaryhttp//notaries-r-
  su.comgt
• XQ34Z-4G5
• lt/notarytokengt
• lt/soapenvHeadergt
• ltsoapenvBodygt
• ltpo id2352 submitted2004-01-05
  custID73852gt
• normal purchase order info
• lt/pogt
• lt/soapenvBodygt
• lt/soapenvEnvelopegt

13
Header Uses

• Extending messaging infrastructure headers are
  usually processed by middleware. Applications
  may not even see them
• Defining orthogonal data A way to send
  information to the application without having to
  change the document schema

14
mustUnderstand Flag

• Some headers carry useful but not critical
  information about the message
• Some headers must be processed in order for the
  body message to make sense
• ltsoapenvHeadergt
• ltnotarytoken xmlnsnotaryhttp//notaries-r-
  su.com
• soapenvmustUnderstandtruegt
• XQ34Z-4G5
• lt/notarytokengt
• lt/soapenvHeadergt

15
mustUnderstand Flag

• If true an application must be able to process
  the header in order to correctly process the
  message
• If false or missing, the application can safely
  process the message without processing the header
• The flag allows you to build extensions that
  fundamentally change the way a document is
  processed and in a way that is interoperable
• Applications can gracefully fail using the flag

16
SOAP Modules

• If you are adding headers you probably want other
  parties to use your extension
• Usually a specification is written that covers
  the details of the constraints, rules,
  preconditions, and data formats of the extension
• These specifications are called SOAP modules
• Modules are named with URIs

17
SOAP Intermediaries

• Vertical extensibility is about adding new
  information within a SOAP message
• Horizontal extensibility is about targeting
  different parts of the same SOAP message to
  different recipients
• Horizontal extensibility is provided by SOAP
  intermediaries

18
Why Intermediaries?

• Intermediaries are applications that can process
  parts of a SOAP message as it travels from origin
  to destination
• The route taken by the message is called the SOAP
  message path

Requester
Provider
Intermediary
Intermediary
19
Why Intermediaries?

• Intermediaries can accept and forward SOAP
  messages
• Intermediaries can process messages
• Three use cases
• Crossing trust domains
• Ensuring scalability
• Providing value-added services

20
Crossing Trust Domains

• Employees and customers are probably kept in
  different trust domains. Internet requests can
  be processed by an intermediary before crossing
  into a trusted domain to be processed

21
Scalability

• Highly scalable systems may require buffering of
  messages and routing of messages based on
  parameters contained in headers
• Users are unaware of the extra processing by
  intermediaries

22
Some Value-added Services

• Securing message exchanges through untrustworth
  domains An intermediary encrypts a message and
  signs it before sending the message. Another
  intermediary receives the message, checks the
  digital signature, and decrypts the message
• Notarization/nonrepudiation A third party
  records an interaction
• Providing message tracing facilities Discover
  the path a message took along with timings

23
Transparent and Explicit Intermediaries

• A transparent intermediary is one the client
  knows nothing about. The client thinks the
  message is going straight to the service endpoint
• An explicit intermediary is one in which the
  client knows that the message will travel through
  an intermediary

24
SOAP Intermediaries

• SOAP was designed with intermediaries in mind
• Three aspects of intermediary-enabled
  architecture
• How do you pass information to intermediaries?
• How do you identify who should process what?
• What happens to information that is processed by
  intermediaries

25
Identification of Intermediaries

• All headers can optionally have a soapenvrole
  attribute
• The value of the attribute is a URI that
  identifies the intermediary
• The URI might mean a particular node (Johns
  machine) or it might mean a class of nodes (any
  cache manager along the path)
• A given node can play multiple roles (Johns
  machine might be a cache manager)

26
Node Processing Steps

• Each node must collect all headers targeted at
  the node
• Each node looks at the headers marked
  mustUnderstand and verifies it can process the
  header in accordance with the rules associated
  with that header
• If if finds a mustUnderstand header it doesnt
  recognize, it must immediately stop processing

27
Special Values of Attribute role

• http//www.w3.org/2003/05/soap-envelope/role/next
  Indicates the header entrys recipient is the
  next SOAP node that processes the message good
  for hop-by-hop message processing
• http//www.w3.org/2003/05/soap-envelope/role/ultim
  ateReceiver Refers to the final recipient of
  the message. Omitting this implies that the final
  recipient should process the header. The final
  recipient also processes the body

28
Special Values of Attribute role

• http//www.w3.org/2003/05/soap-envelope/role/none
  Indicates that no SOAP node should process this
  header. The node still might read information in
  the node

29
Types of Intermediaries

• Forwarding Intermediary these intermediaries
  process only certain headers and forward the
  message to the next node in the path
• Active Intermediary Process and perhaps modify
  a message in ways not defined by the message
  contents. For example adding a digital signature
  to every outbound message

30
Intermediary Rules and Headers

• All headers targeted at a particular intermediary
  are removed from the message when its forwarded
  to the next node
• The contract implied by a given header is between
  the sender of that header and the first node
  satisfying the role to which its targeted
• Headers that arent targeted at a particular
  intermediary should be forwarded through
  untouched
• Either type of intermediary may do work on the
  message

31
Intermediary Rules and Headers

• Headers are removed by a target even if they
  arent understood
• Two exceptions
• The specification for a given extension indicates
  that a copy of the header should be placed in the
  outgoing message (reinserted)
• When you want to indicate to an intermediary that
  extensions targeted at them but not understood
  should be passed through. Soap 1.2 has a relay
  attribute for this purpose

32
The SOAP Body

• The SOAP Body element surrounds the information
  that is core to the SOAP message
• All immediate children of the Body element are
  body entries (bodies)
• Bodies contain arbitrary XML.
• Based on the intent of the SOAP message, certain
  conventions govern the format of the SOAP body
  (for example, RPCs)
• When a node identifies itself as the ultimate
  recipient, its required to process the contents
  of the body which carries the core of the SOAP
  message

33
The SOAP Processing Model

• Steps a processor must perform when a SOAP
  message is received
• Determine the set of roles in which the node is
  to act. The contents of the envelope, including
  any headers and the body may be inspected in
  making this determination
• Identify all header blocks targeted at the node
  that are mandatory

34
The SOAP Processing Model

• Steps a processor must perform when a SOAP
  message is received
• If one or more header blocks arent understood by
  the node, generate a single SOAP fault with the
  value of Code set to envmustUnderstand. No
  further processing is done. Faults related to
  the body must not be generated in this step
• Process all mandatory headers targeted at the
  node, and in the case of ultimate receiver, the
  body. Non-mandatory headers directed at the node
  can also be processed

35
The SOAP Processing Model

• Steps a processor must perform when a SOAP
  message is received
• 5. In the case of an intermediary where the
  message exchange pattern and processing require
  the message to be relayed, do so.

36
Versioning in SOAP

• The SOAP envelope does not expose any explicit
  version information (like HTTP or XML)
• Instead, SOAP uses namespaces to define a
  protocol version using a URI
• Web service engines have a choice of how to treat
  SOAP messages that have a version other than the
  one the engine is best suited to process

37
Versioning in SOAP

• Suppose and engine reads a message
• If the message version is the same as any version
  the engine knows, it can process the message
• If the message version is older than any version
  the engine knows, it should generate a
  VersionMismatch fault and attempt to negotiate
  the protocol version with the client by sending
  info about the versions it can accept
• If the message version is newer than any version
  the engine knows, it must generate
  VersionMismatch fault

38
Processing Headers and Bodies

• The SOAP definition of process is to fulfill
  the contract indicated by a particular piece of a
  SOAP message (header or body)
• An intermediary might encrypt the body of a
  message as it passes through, but this is not
  processing in the SOAP sense. The intermediary
  isnt doing something the body requested
• A header added to supply data (instead of
  changing the body and schema) might add none to
  the role to make sure no one tries to process it

39
Faults Error Handling in SOAP

• A SOAP fault message is a normal SOAP message
  with a well-known element soapenvFault
• The presence of soapenvFault signals processors
  that something has gone wrong
• The fault code can signal exactly what is wrong

40
Faults Error Handling in SOAP

• ltenvHeadergt
• ltstPSAnnouncegtServices unavailable after
  5PMlt/stPSAnnouncegt
• lt/envHeadergt
• ltenvBodygt
• ltenvFaultgt
• ltenvCodegt
• ltenvValuegtenvSenderlt/envValuegt
• ltenvSubcodegt
• ltenvValuegtstInvalid POlt/envValuegt
• lt/envSubcodegt
• lt/envCodegt
• ltenvReasongt
• ltenvText xmllangen-USgtPO didnt
  validatelt/envTextgt
• lt/envReasongt
• ltenvDetailgt lt/envDetailgt
• lt/envFaultgt
• lt/envBodygt
• lt/envEnvelope

41
Fault Code

• Sender the problem is missing or incorrect data
  from the sender
• Receiver Something went wrong with the receiver
  while processing the message. Not directly
  attributable to the sender
• mustUnderstand a header was received that was
  targeted to the receiving node marked
  mustUnderstandtrue, and was not understood
• VersionMismatch the namespace on the SOAP
  envelope isnt compatible with the version on the
  receiver

42
Subcodes

• You can specify an arbitrary hierarchy of
  subcodes
• ltenvCodegt
• ltenvValuegtenvSenderlt/envValuegt
• ltenvSubcodegt
• ltenvValuegtstInvalid POlt/envValuegt
• lt/envSubcodegt
• lt/envCodegt
• Each subcode can contain another subcode

43
Reason

• The Reason element contains human readable
  descriptions of the fault
• The Text element contains the text
• Multiple Text elements can be coded but each one
  should have a different language
• ltenvReasongt
• ltenvText xmllangen-USgtPO didnt
  validatelt/envTextgt
• lt/envReasongt

44
Node and Role

• An optional Node element can indicate which node
  (sender, intermediary, ultimate destination) was
  processing the message when the fault occurred.
  It contains a URI
• The Role element indicates which role the
  faulting node was playing when the fault occurred.

45
Fault Details

• We may want to pass back complex machine-readable
  data (stack trace)
• You can place anything inside the Detail element

46
Using Headers in Faults

• Since Faults are messages, they can contain
  headers
• Some headers are specifically for faults
• NotUnderstood header used to indicate which
  header was not understood. Multiple headers of
  this type can be coded
• Upgrade header used to indicate a versioning
  problem

47
Objects in XML SOAP Data Model

• In order for programmers to send Java/C/VB
  objects in SOAP envelopes, two concepts were
  introduced
• SOAP Data model
• SOAP encoding

48
Objects in XML

• The SOAP data model is an abstract representation
  of data structure in Java
• The encoding is a set of rules that map the data
  model into XML

49
Java Data Model
129

• Class Product
• String description
• String sku
• double unitPrice

unitPrice
Product
description
sku
skateboard
947-x
50
Object Graphs

• Nodes can have outgoing edges (compound values)
• Nodes can have only incoming edges (simple
  values)
• Edges coming out of a compound value have names
  and the node represents a structure
• The edge names (accessors) are equivalent to
  field names in Java
• A node with outgoing edges that are only
  distiquished by position represents an array

51
Multireference values

• The same value can be referred two more than once

pet
pet
52
The SOAP Encoding

• The encoding is used to convert the model to XML
• ltproduct soapenvencodingStylehttp//www.w3.org/
  2003/05/soap-encodinggt
• ltskugt947-xlt/skugt
• ltdescriptiongtskateboardlt/descriptiongt
• ltunitpricegt129lt/unitpricegt
• lt/productgt
• Multirefs cause a small problems

53
Encoding Arrays

• ltmyArray soapencitemTypexsdstring
  soapencarraySize3gt
• ltitemgtHueylt/itemgt
• ltitemgtDueylt/itemgt
• ltitemgtLouielt/itemgt
• lt/myArraygt

54
SOAP RPC Conventions

• Data model can be used to map a procedure call to
  SOAP
• Java public int addFive(int arg)
• ltenvEnvelopegt
• ltenvBodygt
• ltmyNSaddFive xmlnsmyNShttp//mydomain.com/
  encencodingStylehttp//gt
• ltarg xsitypexsdintgt33lt/arggt
• lt/myNSaddFivegt
• lt/envBodygt
• lt/envEnvelopegt

55
RPC Response

• The RPC response might look like this
• ltenvEnvelopegt
• ltenvBodygt
• ltmyNSaddFiveResponse xmlnsmyNShttp//mydomai
  n.com/
• xmlnsrpchttp//www.w3.org/2003/05/so
  ap-rpc
• encencodingStylehttp//gt
• ltrpcresultgtretlt/rpcresultgt
• ltret xsitypexsdintgt38lt/retgt
• lt/myNSaddFiveResponsegt
• lt/envBodygt
• lt/envEnvelopegt